Skip to main content
GET
/
api
/
trading
/
{exchange}
/
balances
Get Balance by Exchange
curl --request GET \
  --url https://api.tide.ag/api/trading/{exchange}/balances \
  --header 'X-API-KEY: <api-key>'
{
  "success": true,
  "data": {
    "success": true,
    "exchange": "hyperliquid",
    "address": "<string>",
    "balances": [
      {
        "asset": "USDC",
        "free": "<string>",
        "locked": "<string>",
        "total": "<string>",
        "crossWalletBalance": "<string>",
        "crossUnPnl": "<string>",
        "maxWithdrawAmount": "<string>"
      }
    ],
    "withdrawable": "<string>",
    "accountValue": "<string>"
  },
  "timestamp": 123
}
Retrieve account balances for a specific exchange and wallet address. This endpoint provides detailed balance information including available, locked, and total amounts for each asset.

​
Features

  • Multi-exchange support: Query balances from Hyperliquid, Lighter, Aster, and Avantis
  • Wallet-based queries: Fetch balances for any EVM wallet address
  • Detailed balance breakdown: Free, locked, and total amounts per asset
  • Exchange-specific fields: Additional metadata like collateral, account index, and PnL

​
Request

  • Method: GET
  • Endpoint: /api/trading/{exchange}/balances
  • Path Parameters: exchange (required - hyperliquid, lighter, aster, or avantis)
  • Headers: x-wallet-id (required for Hyperliquid - Wallet UUID)
  • Query Parameters: walletAddress (required for Lighter/Aster - EVM wallet address)

​
Hyperliquid

curl -X GET "https://api.tide.ag/api/trading/hyperliquid/balances" \
  -H "x-wallet-id: a1e82339-29f8-41a6-a468-ce8d268a3261" \
  -H "Content-Type: application/json"

​
Lighter / Aster

curl -X GET "https://api.tide.ag/api/trading/lighter/balances?walletAddress=0xE7bECcEC683a6e141EaD23237088CfbC348b2295" \
  -H "Content-Type: application/json"

​
Response Example

​
Hyperliquid

{
  "success": true,
  "data": {
    "exchange": "hyperliquid",
    "address": "a1e82339-29f8-41a6-a468-ce8d268a3261",
    "balances": [
      {
        "asset": "USDC",
        "free": "7.083528",
        "locked": "0",
        "total": "7.083528"
      }
    ]
  },
  "timestamp": 1764687746160
}

​
Lighter

{
  "success": true,
  "data": {
    "success": true,
    "exchange": "lighter",
    "address": "0xE7bECcEC683a6e141EaD23237088CfbC348b2295",
    "accountIndex": 316225,
    "balances": [
      {
        "asset": "USDC",
        "free": "5.014025",
        "total": "5.014025"
      }
    ],
    "collateral": "5.014025",
    "availableBalance": "0",
    "accountType": "standard"
  },
  "timestamp": 1762764977739
}

​
Aster

{
  "success": true,
  "data": {
    "feeTier": 0,
    "canTrade": true,
    "canDeposit": true,
    "canWithdraw": true,
    "updateTime": 0,
    "totalInitialMargin": "0.00000000",
    "totalMaintMargin": "0.00000000",
    "totalWalletBalance": "4.52534689",
    "totalUnrealizedProfit": "0.00000000",
    "totalMarginBalance": "4.52534689",
    "totalPositionInitialMargin": "0.00000000",
    "totalOpenOrderInitialMargin": "0.00000000",
    "totalCrossWalletBalance": "4.52534689",
    "totalCrossUnPnl": "0.00000000",
    "availableBalance": "4.52444185",
    "maxWithdrawAmount": "4.52534689",
    "assets": []
  }
}

​
Avantis

curl -X GET "https://api.tide.ag/api/balances/0xabc123..." \
  -H "Content-Type: application/json"

​
Avantis Response

{
  "success": true,
  "data": {
    "avantis": {
      "usdc": "500.00",
      "availableBalance": "350.00"
    }
  }
}
The Avantis balance endpoint uses /api/balances/:walletAddress (not the exchange-specific path). The usdc field represents total USDC on Base, while availableBalance is total minus deployed collateral.

​
Aster Endpoint

GET /api/aster/perp/:walletId/account Path Parameters:
ParameterTypeRequiredDescription
walletIdstringYesWallet ID (UUID)
Example Request: 
curl -X GET https://api.tide.ag/api/aster/perp/ee337309-3e77-4278-b21a-4681468168ba/account \
  -H "Content-Type: application/json"

​
Use Cases

  • Display account overview and portfolio value across exchanges
  • Validate order placement against available balance
  • Monitor asset distribution across multiple venues
  • Track collateral and margin requirements

​
Authentication

  • Hyperliquid: No authentication required (public API)
  • Lighter: No authentication required (public API)
  • Aster: Requires HMAC-SHA256 credentials configured on the server
  • Avantis: No authentication required (public API, wallet address only)
Aster requires ASTER_API_KEY and ASTER_API_SECRET environment variables to be configured on the API server.

​
Response Fields

​
Common Fields (All Exchanges)

  • success — Request status
  • exchange — Exchange identifier
  • address — Wallet address (checksum format)
  • balances — Array of asset balances
  • timestamp — Unix timestamp in milliseconds

​
Balance Object Fields

  • asset — Asset symbol (e.g., USDC)
  • free — Available balance for trading
  • total — Total balance (free + locked)
  • locked — Balance locked in orders/positions (Aster only)

​
Exchange-Specific Fields

Hyperliquid:
  • withdrawable — Amount available for withdrawal
  • accountValue — Total account value including positions
Lighter:
  • accountIndex — Lighter account index
  • collateral — Total collateral
  • availableBalance — Available for new positions
  • accountType — Account type (standard/isolated)
Aster:
  • accountType — Account type (futures/spot)
  • crossWalletBalance — Cross margin balance
  • crossUnPnl — Unrealized PnL
  • maxWithdrawAmount — Maximum withdrawable amount
Avantis:
  • usdc — Total USDC balance on Base
  • availableBalance — Available balance (total minus deployed collateral)

​
Address Format

All wallet addresses are automatically converted to checksum format. You can provide addresses in any format:
  • Lowercase: 0xe7beccec683a6e141ead23237088cfbc348b2295
  • Uppercase: 0xE7BECCEC683A6E141EAD23237088CFBC348B2295
  • Checksum: 0xE7bECcEC683a6e141EaD23237088CfbC348b2295
For real-time balance updates when orders execute or positions change, use the WebSocket balances topic.

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
exchange
enum<string>
required

Exchange name

Available options:
hyperliquid,
lighter,
aster,
avantis

Query Parameters

​
walletAddress
string
required

EVM wallet address (0x...)

Response

Balance data for the specified exchange

​
success
boolean
​
data
object
​
timestamp
integer

Unix timestamp in milliseconds