Skip to main content
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>'
{
  "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
}
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

NameTypeRequiredDescription
walletAddressstring✅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

NameTypeRequiredDescription
exchangestring✅Venue to query (lighter, aster, hyperliquid, or avantis)
walletAddressstring✅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

ParameterTypeRequiredDescription
walletIdstringYesWallet ID (UUID)

​
Query Parameters

ParameterTypeRequiredDescription
symbolstringNoFilter 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

FieldTypeDescription
symbolstringTrading pair
positionAmtstringPosition size (positive for LONG, negative for SHORT)
entryPricestringAverage entry price
markPricestringCurrent mark price
unRealizedProfitstringUnrealized PnL
liquidationPricestringLiquidation price
leveragestringCurrent leverage
marginTypestring”cross” or “isolated”
positionSidestring”BOTH”, “LONG”, or “SHORT”
notionalstringPosition notional value
updateTimenumberLast 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

FieldTypeDescription
symbolstringAsset symbol (e.g., “ETH”, “BTC”)
exchangestringAlways "avantis"
directionstring"LONG" or "SHORT"
sizestringToken amount (e.g., “0.032416”)
entryPricestringEntry price in USD
markPricestringCurrent mark price in USD
liquidationPricestringLiquidation price in USD, or "-"
unrealizedPnlstringUnrealized PnL in USD (rollover fees only, no live PnL from backend)
unrealizedPnlPercentstringUnrealized PnL as percentage
leveragenumberPosition leverage
collateralstringCollateral in USDC
marginstringMargin in USDC
timestampnumberPosition opened timestamp (ms)
isZfpbooleanWhether this is a zero-fee position
walletAddressstringWallet 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[]
​
totalPositions
integer

Number of active positions