Get Open Positions

Get Open Positions (All Exchanges)

curl --request GET \
  --url https://api.tide.ag/api/trading/positions/all/{walletAddress} \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.tide.ag/api/trading/positions/all/{walletAddress}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tide.ag/api/trading/positions/all/{walletAddress}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tide.ag/api/trading/positions/all/{walletAddress}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tide.ag/api/trading/positions/all/{walletAddress}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "walletAddress": "<string>",
  "positions": [
    {
      "symbol": "BTC",
      "exchange": "hyperliquid",
      "direction": "LONG",
      "size": "<string>",
      "entryPrice": "<string>",
      "markPrice": "<string>",
      "liquidationPrice": "<string>",
      "unrealizedPnl": "<string>",
      "unrealizedPnlPercent": "<string>",
      "leverage": 123,
      "collateral": "<string>",
      "margin": "<string>",
      "timestamp": 123,
      "walletAddress": "<string>"
    }
  ],
  "totalPositions": 123
}

{
  "success": false,
  "error": "Invalid wallet address format"
}

{
  "success": false,
  "error": "Missing or invalid credentials for Aster"
}

{
  "success": false,
  "error": "Failed to fetch open positions: timeout"
}

GET

api

trading

positions

all

{walletAddress}

Get Open Positions (All Exchanges)

curl --request GET \
  --url https://api.tide.ag/api/trading/positions/all/{walletAddress} \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.tide.ag/api/trading/positions/all/{walletAddress}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tide.ag/api/trading/positions/all/{walletAddress}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tide.ag/api/trading/positions/all/{walletAddress}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tide.ag/api/trading/positions/all/{walletAddress}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "walletAddress": "<string>",
  "positions": [
    {
      "symbol": "BTC",
      "exchange": "hyperliquid",
      "direction": "LONG",
      "size": "<string>",
      "entryPrice": "<string>",
      "markPrice": "<string>",
      "liquidationPrice": "<string>",
      "unrealizedPnl": "<string>",
      "unrealizedPnlPercent": "<string>",
      "leverage": 123,
      "collateral": "<string>",
      "margin": "<string>",
      "timestamp": 123,
      "walletAddress": "<string>"
    }
  ],
  "totalPositions": 123
}

{
  "success": false,
  "error": "Invalid wallet address format"
}

{
  "success": false,
  "error": "Missing or invalid credentials for Aster"
}

{
  "success": false,
  "error": "Failed to fetch open positions: timeout"
}

Fetch normalized open positions for a wallet across all connected derivatives venues. The aggregator fans out to Lighter, Aster, Hyperliquid, and Avantis, returning consistent leverage, collateral, and PnL metrics in one payload.

All Exchanges

Method: GET
Endpoint: /api/trading/positions/all/{walletAddress}
Authentication: Required

Path Parameters

Name	Type	Required	Description
`walletAddress`	string	✅	Wallet address to query across all venues

Example

curl -X GET "https://api.tide.ag/api/trading/positions/all/0xabc123..."

Sample Response

{
  "success": true,
  "walletAddress": "0xabc123...",
  "positions": [
    {
      "exchange": "lighter",
      "symbol": "BTC",
      "size": "0.25",
      "entryPrice": "49850.00",
      "direction": "LONG",
      "leverage": 10,
      "unrealizedPnl": "150.25",
      "collateral": "500.00"
    },
    {
      "exchange": "aster",
      "symbol": "ETH",
      "size": "1.5",
      "entryPrice": "2400.00",
      "direction": "SHORT",
      "leverage": 5,
      "unrealizedPnl": "-45.10",
      "collateral": "750.00"
    },
    {
      "exchange": "avantis",
      "symbol": "ETH",
      "size": "0.032416",
      "entryPrice": "3420.50",
      "direction": "LONG",
      "leverage": 10,
      "unrealizedPnl": "-1.25",
      "collateral": "100.00"
    }
  ],
  "totalPositions": 3
}

The positions array contains one entry per venue position. Zero-size positions are automatically filtered out.

Single Exchange

Method: GET
Endpoint: /api/trading/{exchange}/positions/{walletAddress}
Authentication: Required

Path Parameters

Name	Type	Required	Description
`exchange`	string	✅	Venue to query (`lighter`, `aster`, `hyperliquid`, or `avantis`)
`walletAddress`	string	✅	Wallet address to inspect on that venue

Example

curl -X GET "https://api.tide.ag/api/trading/lighter/positions/0xabc123..."

Sample Response

{
  "success": true,
  "exchange": "lighter",
  "walletAddress": "0xabc123...",
  "positions": [
    {
      "symbol": "BTC",
      "size": "0.25",
      "direction": "LONG",
      "entryPrice": "49850.00",
      "leverage": 10
    }
  ],
  "totalPositions": 1
}

Aster - Get Positions

Get open positions on Aster exchange.

Endpoint

GET /api/aster/perp/:walletId/positions

Path Parameters

Parameter	Type	Required	Description
`walletId`	string	Yes	Wallet ID (UUID)

Query Parameters

Parameter	Type	Required	Description
`symbol`	string	No	Filter by trading pair (e.g., “BTCUSDT”)

Example Request

curl -X GET "https://api.tide.ag/api/aster/perp/ee337309-3e77-4278-b21a-4681468168ba/positions?symbol=BTCUSDT" \
  -H "Content-Type: application/json"

Success Response

{
  "success": true,
  "data": {
    "positions": [
      {
        "symbol": "BTCUSDT",
        "positionAmt": "0.001",
        "entryPrice": "86517.4",
        "markPrice": "86530.48025725",
        "unRealizedProfit": "0.01308025",
        "liquidationPrice": "82232.28189664",
        "leverage": "20",
        "maxNotionalValue": "12500000",
        "marginType": "cross",
        "isolatedMargin": "0.00000000",
        "isAutoAddMargin": "false",
        "positionSide": "BOTH",
        "notional": "86.53048025",
        "isolatedWallet": "0",
        "updateTime": 1764640755161
      }
    ],
    "total": 1
  }
}

Response Fields

Field	Type	Description
`symbol`	string	Trading pair
`positionAmt`	string	Position size (positive for LONG, negative for SHORT)
`entryPrice`	string	Average entry price
`markPrice`	string	Current mark price
`unRealizedProfit`	string	Unrealized PnL
`liquidationPrice`	string	Liquidation price
`leverage`	string	Current leverage
`marginType`	string	”cross” or “isolated”
`positionSide`	string	”BOTH”, “LONG”, or “SHORT”
`notional`	string	Position notional value
`updateTime`	number	Last update timestamp (ms)

Avantis - Get Positions

Get open positions on Avantis exchange (perpetual trading on Base).

Endpoint

GET /api/trading/positions/all/{walletAddress} Avantis positions are returned within the aggregated positions response under data.positions.avantis.

Avantis Position Response Shape

{
  "success": true,
  "data": {
    "positions": {
      "avantis": {
        "positions": [
          {
            "symbol": "ETH",
            "exchange": "avantis",
            "direction": "LONG",
            "size": "0.032416",
            "entryPrice": "3420.50",
            "markPrice": "3420.50",
            "liquidationPrice": "3100.25",
            "unrealizedPnl": "-1.25",
            "unrealizedPnlPercent": "-1.25",
            "leverage": 10,
            "collateral": "100.00",
            "margin": "100.00",
            "timestamp": 1698840000000,
            "isZfp": false,
            "walletAddress": "0xabc123..."
          }
        ],
        "count": 1
      }
    }
  }
}

Avantis Position Fields

Field	Type	Description
`symbol`	string	Asset symbol (e.g., “ETH”, “BTC”)
`exchange`	string	Always `"avantis"`
`direction`	string	`"LONG"` or `"SHORT"`
`size`	string	Token amount (e.g., “0.032416”)
`entryPrice`	string	Entry price in USD
`markPrice`	string	Current mark price in USD
`liquidationPrice`	string	Liquidation price in USD, or `"-"`
`unrealizedPnl`	string	Unrealized PnL in USD (rollover fees only, no live PnL from backend)
`unrealizedPnlPercent`	string	Unrealized PnL as percentage
`leverage`	number	Position leverage
`collateral`	string	Collateral in USDC
`margin`	string	Margin in USDC
`timestamp`	number	Position opened timestamp (ms)
`isZfp`	boolean	Whether this is a zero-fee position
`walletAddress`	string	Wallet address that owns the position

Avantis markPrice returned from the backend matches entryPrice — live mark prices are not provided by the backend. For real-time mark prices, use the client-side Pyth oracle price feed.

Credential Payload

Supply only the credential blocks for venues you want to query. The service reads them per request and does not persist any keys.

{
  "credentials": {
    "lighter": {
      "apiKeyPrivateKey": "0x...",
      "accountIndex": 0
    },
    "aster": {
      "apiKey": "...",
      "apiSecret": "...",
      "walletAddress": "0x..."
    },
    "hyperliquid": {
      "privateKey": "0x..."
    }
  }
}

Errors

400 – { "success": false, "error": "Invalid wallet address format" }
401 – { "success": false, "error": "Missing or invalid credentials for Aster" }
500 – { "success": false, "error": "Failed to fetch open positions: timeout" }

For live updates subscribe to the WebSocket positions topic; REST calls return a snapshot at the time of the request.

Authorizations

X-API-KEY

string

header

required

API key for authentication. Also requires X-API-SECRET, X-API-TIMESTAMP, and X-API-SIGNATURE headers for private endpoints.

Path Parameters

walletAddress

string

required

Wallet address to query across all venues

Response

Open positions grouped across exchanges

success

boolean

walletAddress

string

positions

object[]

Show child attributes

totalPositions

integer

Number of active positions

Getting Started

Market Data

Trading

Positions

Account

System

Guides

All Exchanges

Path Parameters

Example

Sample Response

Single Exchange

Path Parameters

Example

Sample Response

Aster - Get Positions

Endpoint

Path Parameters

Query Parameters

Example Request

Success Response

Response Fields

Avantis - Get Positions

Endpoint

Avantis Position Response Shape

Avantis Position Fields

Credential Payload

Errors

Authorizations

Path Parameters

Response

​All Exchanges

​Path Parameters

​Example

​Sample Response

​Single Exchange

​Path Parameters

​Example

​Sample Response

​Aster - Get Positions

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Success Response

​Response Fields

​Avantis - Get Positions

​Endpoint

​Avantis Position Response Shape

​Avantis Position Fields

​Credential Payload

​Errors

Authorizations

Path Parameters

Response

All Exchanges

Path Parameters

Example

Sample Response

Single Exchange

Path Parameters

Example

Sample Response

Aster - Get Positions

Endpoint

Path Parameters

Query Parameters

Example Request

Success Response

Response Fields

Avantis - Get Positions

Endpoint

Avantis Position Response Shape

Avantis Position Fields

Credential Payload

Errors