Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/bitmart-api/llms.txt

Use this file to discover all available pages before exploring further.

The position and leverage endpoints give you full control over how your futures exposure is managed — from viewing current open positions and their liquidation prices, to adjusting leverage and switching between one-way and hedge position modes. All methods on this page require authentication (SIGNED).
Leverage amplifies both gains and losses. High leverage significantly increases the risk of liquidation. Always verify your margin balance and liquidation price before increasing leverage on an open position. Never risk more than you can afford to lose.

​
Setup

import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

​
Viewing Positions

​
getFuturesAccountPositions(params?)

Returns all currently open futures positions. Optionally filter by symbol or sub-account. Signature 
getFuturesAccountPositions(params?: {
  symbol?: string;
  account?: string;
}): Promise<APIResponse<FuturesAccountPosition[]>>
​
symbol
string
Optional contract symbol filter (e.g. BTCUSDT). Omit to retrieve all open positions.
​
account
string
Optional account type filter (e.g. futures).
Response fields (FuturesAccountPosition) 
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const positions = await client.getFuturesAccountPositions();

for (const pos of positions.data) {
  const side = pos.position_type === 1 ? 'LONG' : 'SHORT';
  console.log(
    `${pos.symbol} ${side}: size=${pos.current_amount}, entry=${pos.entry_price}, PnL=${pos.unrealized_value}`
  );
}

​
getFuturesAccountPositionsV2(params?)

Enhanced version of getFuturesAccountPositions with additional fields including position_side, unrealized_pnl, liquidation_price, initial_margin, and max_notional_value. Signature 
getFuturesAccountPositionsV2(params?: {
  symbol?: string;
  account?: string;
}): Promise<APIResponse<FuturesAccountPositionV2[]>>
Accepts the same optional params as V1. Additional fields in V2 (FuturesAccountPositionV2)
FieldTypeDescription
position_sidestringLong or Short (explicit string)
open_typestringMargin type: cross or isolated
unrealized_pnlstringUnrealised profit/loss
liquidation_pricestringPrice at which position is liquidated
initial_marginstringInitial margin locked for the position
max_notional_valuestringMaximum allowed notional value
mark_valuestringCurrent mark price × position size
position_amountstringPosition size in contract units
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const positions = await client.getFuturesAccountPositionsV2({ symbol: 'BTCUSDT' });

for (const pos of positions.data) {
  console.log(`${pos.symbol} ${pos.position_side}`);
  console.log(`  Entry: ${pos.entry_price} | Mark: ${pos.mark_price}`);
  console.log(`  Unrealised PnL: ${pos.unrealized_pnl}`);
  console.log(`  Liquidation price: ${pos.liquidation_price}`);
  console.log(`  Initial margin: ${pos.initial_margin}`);
}
Prefer getFuturesAccountPositionsV2 for new integrations. The V2 response includes liquidation_price and unrealized_pnl as top-level fields, making risk monitoring simpler.

​
getPositionRiskDetails(params?)

Returns detailed risk metrics for open positions, including isolation margin, leverage, and max notional value per position. Signature 
getPositionRiskDetails(params?: {
  symbol?: string;
  account?: string;
}): Promise<APIResponse<PositionRisk[]>>
​
symbol
string
Optional contract symbol filter.
​
account
string
Optional account type filter.
Response fields (PositionRisk)
FieldTypeDescription
symbolstringContract symbol
position_amtstringPosition size
mark_pricestringCurrent mark price
unrealized_profitstringUnrealised PnL
liquidation_pricestringEstimated liquidation price
leveragestringCurrent leverage
max_notional_valuestringMaximum position notional value
margin_typestringCross or Isolated
isolated_marginstringIsolated margin allocated (if applicable)
position_sidestringLong or Short
notionalstringCurrent notional value
update_timenumberLast update time (Unix ms)
accountstringAccount identifier
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const risks = await client.getPositionRiskDetails();

for (const risk of risks.data) {
  const markPrice = parseFloat(risk.mark_price);
  const liqPrice = parseFloat(risk.liquidation_price);

  const distanceToLiq =
    risk.position_side === 'Long'
      ? ((markPrice - liqPrice) / markPrice) * 100
      : ((liqPrice - markPrice) / markPrice) * 100;

  console.log(
    `${risk.symbol} ${risk.position_side}: liq at ${risk.liquidation_price} ` +
    `(${distanceToLiq.toFixed(2)}% away), leverage ${risk.leverage}x`
  );
}

​
Leverage Management

​
setFuturesLeverage(params)

Sets the leverage for a specific futures contract and margin mode. Can be called before or after opening a position. Signature 
setFuturesLeverage(
  params: SetFuturesLeverageRequest,
): Promise<APIResponse<FuturesAccountSetLeverageResult>>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
open_type
string
required
Margin mode: cross or isolated.
​
leverage
string
Leverage multiplier as a string (e.g. "20"). Omit to query the current leverage without changing it.
Response fields (FuturesAccountSetLeverageResult)
FieldTypeDescription
symbolstringContract symbol
leveragestringApplied leverage value
open_typestringMargin mode (cross or isolated)
max_valuestringMaximum allowed leverage for the contract
Increasing leverage on an existing open position will immediately change your liquidation price. Ensure you have sufficient margin before doing so. Reducing leverage requires enough available margin to absorb the change.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const result = await client.setFuturesLeverage({
  symbol: 'BTCUSDT',
  open_type: 'cross',
  leverage: '10',
});

console.log(`Leverage set to ${result.data.leverage}x (max: ${result.data.max_value}x)`);

​
Position Mode

BitMart futures supports two position modes. The mode you choose determines whether you can hold simultaneous long and short positions on the same contract.

​
Position Mode Explained

In one-way mode (one_way_mode), you can only hold one directional position per contract at a time. Opening a position in the opposite direction will reduce or fully close your existing position.
  • Simpler to manage
  • Lower margin requirements
  • Suitable for directional strategies
Changing position mode will fail if you have any open orders or open positions. Close all positions and cancel all orders before switching modes.

​
setPositionMode(params)

Switches the account between one-way mode and hedge mode. Signature 
setPositionMode(params: {
  position_mode: 'hedge_mode' | 'one_way_mode';
}): Promise<APIResponse<{ position_mode: 'hedge_mode' | 'one_way_mode' }>>
​
position_mode
string
required
Position mode to set: hedge_mode or one_way_mode.
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const result = await client.setPositionMode({ position_mode: 'hedge_mode' });
console.log('Position mode set to:', result.data.position_mode);

​
getPositionMode()

Returns the current position mode for your account. Signature 
getPositionMode(): Promise<
  APIResponse<{ position_mode: 'hedge_mode' | 'one_way_mode' }>
>

import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

const mode = await client.getPositionMode();
console.log('Current position mode:', mode.data.position_mode);

if (mode.data.position_mode === 'hedge_mode') {
  console.log('Account supports simultaneous long/short positions');
} else {
  console.log('Account uses one-way directional positions');
}

​
Complete Position Monitoring Example

The following example demonstrates how to build a concise position dashboard combining positions, risk, and leverage information. 
import { FuturesClientV2 } from 'bitmart-api';

const client = new FuturesClientV2({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  apiMemo: process.env.API_MEMO!,
});

async function positionDashboard() {
  // Fetch positions, risk, and position mode in parallel
  const [positions, risks, mode] = await Promise.all([
    client.getFuturesAccountPositionsV2(),
    client.getPositionRiskDetails(),
    client.getPositionMode(),
  ]);

  console.log(`\n=== Futures Position Dashboard ===`);
  console.log(`Mode: ${mode.data.position_mode}`);
  console.log(`Open positions: ${positions.data.length}\n`);

  for (const pos of positions.data) {
    const risk = risks.data.find(
      r => r.symbol === pos.symbol && r.position_side === pos.position_side
    );

    console.log(`${pos.symbol} ${pos.position_side}`);
    console.log(`  Size: ${pos.current_amount} contracts`);
    console.log(`  Entry: $${pos.entry_price} | Mark: $${pos.mark_price}`);
    console.log(`  Unrealised PnL: ${pos.unrealized_pnl}`);
    console.log(`  Leverage: ${pos.leverage}x (${pos.open_type})`);

    if (risk) {
      console.log(`  Liquidation: $${risk.liquidation_price}`);
      console.log(`  Margin: ${risk.margin_type}, isolated: ${risk.isolated_margin}`);
    }
    console.log('');
  }
}

positionDashboard().catch(console.error);

Build docs developers (and LLMs) love

Get started for freeTalk to us