Positions, Margin, and Leverage

Read GET /v1/positions for exposure by instrument, exchange, and settlement asset. Track changes through the positions and risk channels.

Position Fields

A position includes base quantity, side, average entry price, exchange mark price, unrealized P&L, configured leverage, margin mode, and an estimated liquidation price. A zero-quantity stream update closes a position. Liquidation estimates can be null when the exchange has insufficient information to calculate them.

For a linear Binance BTC/USDT long of 0.060 BTC, entry 77,000, and mark 77,100, unrealized P&L is (77,100 − 77,000) × 0.060 = 6 USDT, before fees and funding. Inverse contracts use their own payoff formula.

Cross and Isolated Margin

Cross shares eligible collateral within an exchange account and settlement pool. Isolated reserves collateral for the position. A unified account view preserves the exchange boundaries used for margin and liquidation.

Read margin settings, then update one contract:

import { request } from './rest-client.mjs';

const setting = await request('PUT', '/v1/account/margin-settings', {
  account_id: 'acct_example_main',
  instrument: 'BTC-PERP',
  venue: 'binance',
  settlement_asset: 'USDT',
  margin_mode: 'isolated',
  leverage: '5',
}, 'margin-change-0001');
console.log(setting.margin_mode, setting.leverage);

Leverage is a multiplier: "5" means 5×. Exchange rules, position size, and account risk tiers determine the available range. Some exchanges require open orders and positions to be closed before changing margin mode. Handle MARGIN_MODE_CONFLICT by reading the current position and exchange capabilities.

Monitor Available Margin

GET /v1/account/risk returns equity, initial margin, maintenance margin, available margin, and risk state. Each record states its exchange and settlement asset.

Use margin_ratio as maintenance margin divided by equity. Higher values indicate less headroom. Risk states progress through normal, warning, reduce_only, and liquidating as exchange conditions change. Keep your own strategy limits below the exchange’s liquidation boundary.

A pending custody allocation becomes usable only after exchange acknowledgement. Funding debits, fees, realized losses, and collateral haircuts can change capacity while orders are open. Reconcile risk after these events before adding exposure.