Skip to main content
GET
Get Balance by Exchange
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

Lighter / Aster

Response Example

Hyperliquid

Lighter

Aster

Avantis

Avantis Response

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: Example Request:

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