Skip to main content
GET
/
api
/
trading
/
positions
/
all
/
{walletAddress}
Get Open Positions (All Exchanges)
curl --request GET \
  --url https://api.dexaggregatorbeta.xyz/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, and Hyperliquid, 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.dexaggregatorbeta.xyz/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"
    }
  ],
  "totalPositions": 2
}
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, or hyperliquid)
walletAddressstring✅Wallet address to inspect on that venue

​
Example

curl -X GET "https://api.dexaggregatorbeta.xyz/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.dexaggregatorbeta.xyz/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)

​
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