> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tide.ag/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Open Positions
> Fetch normalized open positions for a wallet across all connected derivatives venues (Lighter, Aster, Hyperliquid, Avantis)
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
```bash theme={null}
curl -X GET "https://api.tide.ag/api/trading/positions/all/0xabc123..."
```
### Sample Response
```json theme={null}
{
"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
```bash theme={null}
curl -X GET "https://api.tide.ag/api/trading/lighter/positions/0xabc123..."
```
### Sample Response
```json theme={null}
{
"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
```bash theme={null}
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
```json theme={null}
{
"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
```json theme={null}
{
"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.
```json theme={null}
{
"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.
## OpenAPI
````yaml GET /api/trading/positions/all/{walletAddress}
openapi: 3.1.0
info:
title: Tide API
description: >-
Decentralized Perpetual Aggregator API for multi-exchange trading across
Hyperliquid, Aster, Lighter, and Pacifica
version: 1.0.0
contact:
name: Tide Support
email: support@tide.ag
url: https://tide.ag
license:
name: MIT
servers:
- url: https://api.tide.ag
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Market Data
description: Public market data endpoints
- name: Trading
description: Order placement and management
- name: Positions
description: Position management and history
- name: Account
description: Account and balance management
- name: System
description: System status and health
paths:
/api/trading/positions/all/{walletAddress}:
get:
tags:
- Positions
summary: Get Open Positions (All Exchanges)
description: >-
Fetch normalized open positions for a wallet across all connected
derivatives venues (Lighter, Aster, Hyperliquid, Avantis)
parameters:
- name: walletAddress
in: path
required: true
schema:
type: string
description: Wallet address to query across all venues
responses:
'200':
description: Open positions grouped across exchanges
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
walletAddress:
type: string
positions:
type: array
items:
$ref: '#/components/schemas/Position'
totalPositions:
type: integer
description: Number of active positions
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Invalid wallet address format
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Missing or invalid credentials for Aster
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: 'Failed to fetch open positions: timeout'
components:
schemas:
Position:
type: object
properties:
symbol:
type: string
example: BTC
description: Asset symbol
exchange:
$ref: '#/components/schemas/ExchangeName'
direction:
$ref: '#/components/schemas/PositionSide'
size:
type: string
description: Position size
entryPrice:
type: string
description: Average entry price
markPrice:
type: string
description: Current mark price
liquidationPrice:
type: string
description: Liquidation price
unrealizedPnl:
type: string
description: Unrealized PnL
unrealizedPnlPercent:
type: string
description: Unrealized PnL percentage
leverage:
type: number
description: Position leverage
collateral:
type: string
description: Collateral amount
margin:
type: string
description: Used margin
timestamp:
type: integer
description: Position timestamp
walletAddress:
type: string
description: Associated wallet address
ExchangeName:
type: string
enum:
- hyperliquid
- aster
- lighter
- pacifica
PositionSide:
type: string
enum:
- LONG
- SHORT
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: >-
API key for authentication. Also requires X-API-SECRET, X-API-TIMESTAMP,
and X-API-SIGNATURE headers for private endpoints.
````