Get Open Positions - Tide API Documentation

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",
      "size": "<string>",
      "entryPrice": "<string>",
      "markPrice": "<string>",
      "liquidationPrice": "<string>",
      "unrealizedPnl": "<string>",
      "unrealizedPnlPercent": "<string>",
      "leverage": 123,
      "collateral": "<string>",
      "margin": "<string>",
      "timestamp": 123,
      "walletAddress": "<string>"
    }
  ],
  "totalPositions": 123
}

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",
      "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

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

Get Routing Recommendation Create Server Wallet

​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