Interface BalanceResponse

Balance information for a trading account on a specific asset.

The balance model tracks funds across three locations:

  • trading_account_balance — funds sitting directly in the trading account contract, ready to be allocated to any market.
  • total_unlocked — the total available balance, i.e. trading_account_balance plus unlocked amounts sitting in individual order-book contracts (e.g. proceeds from filled orders not yet settled). Use this when computing how much you can trade.
  • total_locked — funds locked as collateral for currently open orders across all order-book contracts.

⚠️ total_unlocked already includes trading_account_balance. Do not add them together — that double-counts your funds.

available_for_new_orders = total_unlocked       // correct
locked_in_open_orders   = total_locked
grand_total             = total_unlocked + total_locked

Example

const balances = await client.getBalances(tradeAccountId);
for (const [symbol, bal] of Object.entries(balances)) {
  // ✅ correct: total_unlocked is already the full available balance
  console.log(`${symbol}: available=${bal.total_unlocked}, locked=${bal.total_locked}`);
  // ❌ wrong: do NOT do trading_account_balance + total_unlocked
}
interface BalanceResponse {
    order_books: Record<string, OrderBookBalance>;
    total_locked: bigint;
    total_unlocked: bigint;
    trading_account_balance: bigint;
}

Properties

order_books total_locked total_unlocked trading_account_balance

Properties

order_books

order_books: Record<string, OrderBookBalance>

Per-order-book balance breakdown, keyed by order book contract ID.

total_locked

total_locked: bigint

Total balance locked as collateral for open orders across all order-book contracts (chain integer).

total_unlocked

total_unlocked: bigint

Total available balance for trading (chain integer).

This is trading_account_balance + unlocked amounts in each order-book contract. Use this value — not trading_account_balance alone — when deciding how much you can spend on new orders.

trading_account_balance

trading_account_balance: bigint

Balance sitting directly in the trading account contract (chain integer).

This is a subset of total_unlocked. Do not add these two fields together.

Settings

Member Visibility

On This Page

Properties