BitMart Futures Order Management REST API Reference

The FuturesClientV2 order management endpoints let you submit new futures orders, modify or cancel existing ones, and retrieve the full lifecycle of your orders and trades. All methods on this page require authentication (SIGNED).

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!,
});

Placing Orders

`submitFuturesOrder(params)`

Places a new futures order. Supports limit and market order types with cross or isolated margin modes. Signature

submitFuturesOrder(
  params: SubmitFuturesOrderRequest,
): Promise<APIResponse<FuturesOrderSubmitResult>>

Parameters

symbol

string

required

Contract symbol (e.g. BTCUSDT).

side

number

required

Order side (determines position direction and open/close intent):

Value	Meaning
`1`	`buy_open_long` — Open a long position
`2`	`buy_close_short` — Close a short position (buy back)
`3`	`sell_close_long` — Close a long position (sell)
`4`	`sell_open_short` — Open a short position

type

string

Order type: limit or market. Defaults to limit.

size

number

required

Order quantity in contracts (integer).

price

string

Limit price (required when type is limit).

leverage

string

Leverage multiplier as a string (e.g. "10"). Required for new positions.

open_type

string

Margin mode: cross or isolated.

client_order_id

string

Optional client-defined order ID for idempotency (max 36 characters).

mode

number

Order mode (for hedge-mode accounts):

1 — GTC (Good Till Cancelled)
2 — FOK (Fill or Kill)
3 — IOC (Immediate or Cancel)
4 — Maker-only (Post Only)

preset_take_profit_price

string

Optional take-profit trigger price to attach to the order.

preset_stop_loss_price

string

Optional stop-loss trigger price to attach to the order.

preset_take_profit_price_type

number

Price type for preset take-profit: 1 = last price, 2 = mark price.

preset_stop_loss_price_type

number

Price type for preset stop-loss: 1 = last price, 2 = mark price.

stp_mode

number

Self-trade prevention mode. Controls behaviour when an order would match against another order from the same account.

Response fields (FuturesOrderSubmitResult)

Field	Type	Description
`order_id`	number	Exchange-assigned order ID
`price`	string	Executed or queued price

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 order = await client.submitFuturesOrder({
  symbol: 'BTCUSDT',
  type: 'market',
  side: 1,          // buy_open_long
  size: 1,
  leverage: '10',
  open_type: 'cross',
});

console.log('Order ID:', order.data.order_id);

Use side: 1 (buy_open_long) or side: 4 (sell_open_short) to open new positions. Use side: 2 (buy_close_short) or side: 3 (sell_close_long) to close existing positions.

`updateFuturesLimitOrder(params)`

Modifies the price and/or size of an existing open limit order. Signature

updateFuturesLimitOrder(params: UpdateFuturesLimitOrderRequest): Promise<
  APIResponse<{
    order_id: number;
    client_order_id?: string;
  }>
>

symbol

string

required

Contract symbol (e.g. BTCUSDT).

order_id

number

Exchange order ID to modify. Required if client_order_id is not provided.

client_order_id

string

Client order ID to modify. Required if order_id is not provided.

price

string

New limit price.

size

string

New order quantity (as a string).

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.updateFuturesLimitOrder({
  symbol: 'BTCUSDT',
  order_id: 987654321,
  price: '68000',  // New price
  size: '3',       // New size
});

console.log('Modified order:', result.data.order_id);

Cancelling Orders

`cancelFuturesOrder(params)`

Cancels a single open order by order ID or client order ID. Signature

cancelFuturesOrder(
  params: CancelFuturesOrderRequest,
): Promise<APIResponse<any>>

symbol

string

required

Contract symbol (e.g. BTCUSDT).

order_id

string

Exchange order ID to cancel.

client_order_id

string

Client order ID to cancel.

import { FuturesClientV2 } from 'bitmart-api';

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

await client.cancelFuturesOrder({
  symbol: 'BTCUSDT',
  order_id: '987654321',
});

console.log('Order cancelled');

`cancelAllFuturesOrders(params)`

Cancels all open orders for a specific futures symbol in a single call. Signature

cancelAllFuturesOrders(params: {
  symbol: string;
}): Promise<APIResponse<any>>

symbol

string

required

Contract symbol to cancel all open orders for.

import { FuturesClientV2 } from 'bitmart-api';

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

await client.cancelAllFuturesOrders({ symbol: 'BTCUSDT' });
console.log('All BTCUSDT orders cancelled');

`cancelAllFuturesOrdersAfter(params)`

Sets a dead man’s switch timer. If not refreshed within the specified timeout, all open orders for the symbol are automatically cancelled. Set timeout: 0 to disable. Signature

cancelAllFuturesOrdersAfter(params: {
  timeout: number;
  symbol: string;
}): Promise<APIResponse<any>>

timeout

number

required

Timeout in seconds after which all orders will be cancelled. Set to 0 to disable the timer.

symbol

string

required

Contract symbol.

Call this endpoint periodically (e.g. every 30 seconds) to act as a heartbeat. If your application loses connectivity and cannot refresh, orders will be cancelled automatically after the timeout expires.

import { FuturesClientV2 } from 'bitmart-api';

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

// Cancel all orders if not refreshed within 60 seconds
await client.cancelAllFuturesOrdersAfter({
  symbol: 'BTCUSDT',
  timeout: 60,
});

Querying Orders

`getFuturesAccountOrder(params)`

Fetches the details of a single order by symbol and order ID. Signature

getFuturesAccountOrder(
  params: GetFuturesOrderRequest,
): Promise<APIResponse<FuturesAccountOrder>>

symbol

string

required

Contract symbol.

order_id

string

required

Exchange-assigned order ID.

account

string

Account type filter: futures or copy_trading.

Show FuturesAccountOrder response fields

Field	Type	Description
`order_id`	string	Exchange order ID
`client_order_id`	string	Client-defined order ID
`symbol`	string	Contract symbol
`side`	1\|2\|3\|4	Order side
`type`	string	`limit`, `market`, `liquidate`, `bankruptcy`, `adl`
`size`	string	Order quantity
`price`	string	Order price
`deal_avg_price`	string	Average fill price
`deal_size`	string	Filled quantity
`leverage`	string	Leverage used
`open_type`	string	`cross` or `isolated`
`state`	1\|2\|4	Order state: `1`=active, `2`=filled, `4`=cancelled
`create_time`	number	Creation time (Unix ms)
`update_time`	number	Last update time (Unix ms)

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 order = await client.getFuturesAccountOrder({
  symbol: 'BTCUSDT',
  order_id: '987654321',
});

console.log(`State: ${order.data.state}, Filled: ${order.data.deal_size}/${order.data.size}`);

`getFuturesAccountOrderHistory(params)`

Returns completed (filled, cancelled, or expired) order history for a symbol. Signature

getFuturesAccountOrderHistory(
  params: FuturesAccountHistoricOrderRequest,
): Promise<APIResponse<FuturesAccountHistoricOrder>>

symbol

string

required

Contract symbol.

start_time

number

Start time as Unix timestamp (ms).

end_time

number

End time as Unix timestamp (ms).

account

string

Account type filter.

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 now = Date.now();
const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000;

const history = await client.getFuturesAccountOrderHistory({
  symbol: 'BTCUSDT',
  start_time: oneWeekAgo,
  end_time: now,
});

console.log('Order history:', JSON.stringify(history.data, null, 2));

`getFuturesAccountOpenOrders(params?)`

Returns all currently open (active or partially filled) orders. Signature

getFuturesAccountOpenOrders(
  params?: FuturesAccountOpenOrdersRequest,
): Promise<APIResponse<FuturesAccountOpenOrder[]>>

symbol

string

Filter by contract symbol.

type

string

Filter by order type: limit, market, or trailing.

order_state

string

Filter by state: all (default) or partially_filled.

limit

number

Maximum number of results to return.

import { FuturesClientV2 } from 'bitmart-api';

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

// All open orders
const openOrders = await client.getFuturesAccountOpenOrders();

// Partial fills on BTCUSDT only
const partialOrders = await client.getFuturesAccountOpenOrders({
  symbol: 'BTCUSDT',
  order_state: 'partially_filled',
});

console.log(`Open: ${openOrders.data.length}, Partial: ${partialOrders.data.length}`);

`getFuturesAccountTrades(params)`

Returns a list of your trade fills (executions) with PnL and fee information. Signature

getFuturesAccountTrades(
  params: FuturesAccountTradesRequest,
): Promise<APIResponse<FuturesAccountTrade[]>>

symbol

string

Filter by contract symbol.

start_time

number

Start time as Unix timestamp (ms).

end_time

number

End time as Unix timestamp (ms).

order_id

number

Filter by a specific order ID.

client_order_id

string

Filter by client order ID.

account

string

Account type filter.

Response fields (FuturesAccountTrade)

Field	Type	Description
`trade_id`	string	Unique trade ID
`order_id`	string	Parent order ID
`symbol`	string	Contract symbol
`side`	1\|2\|3\|4	Trade side
`price`	string	Fill price
`vol`	string	Fill quantity
`exec_type`	string	`Taker` or `Maker`
`profit`	boolean	Whether the trade was profitable
`realised_profit`	string	Realised PnL
`paid_fees`	string	Fees paid
`create_time`	number	Trade time (Unix ms)

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 trades = await client.getFuturesAccountTrades({
  symbol: 'BTCUSDT',
  start_time: Date.now() - 86400_000,
  end_time: Date.now(),
});

let totalFees = 0;
for (const trade of trades.data) {
  totalFees += parseFloat(trade.paid_fees);
  console.log(`${trade.exec_type} fill: ${trade.vol} @ ${trade.price}, PnL: ${trade.realised_profit}`);
}
console.log(`Total fees: ${totalFees.toFixed(4)} USDT`);

`getFuturesAccountTransactionHistory(params)`

Returns a detailed ledger of all account transactions including funding settlements, fee payments, deposits, and realised PnL transfers. Signature

getFuturesAccountTransactionHistory(
  params: FuturesAccountHistoricTransactionRequest,
): Promise<APIResponse<FuturesAccountHistoricTransaction[]>>

symbol

string

Filter by contract symbol.

flow_type

number

Transaction type filter:

0 — All
1 — Transfer
2 — Realised PnL
3 — Funding fee
4 — Commission
5 — Liquidation

start_time

number

Start time as Unix timestamp (ms).

end_time

number

End time as Unix timestamp (ms).

page_size

number

Number of records per page.

account

string

Account type filter.

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 txHistory = await client.getFuturesAccountTransactionHistory({
  symbol: 'BTCUSDT',
  flow_type: 0,
  page_size: 50,
});

for (const tx of txHistory.data) {
  console.log(`[${tx.type}] ${tx.amount} ${tx.asset} at ${tx.time}`);
}

Spot (RestClient)

Futures (FuturesClientV2)

Earn & Sub-Accounts

WebSocket Reference

BitMart Futures Order Management REST API Reference

Setup

Placing Orders

`submitFuturesOrder(params)`

`updateFuturesLimitOrder(params)`

Cancelling Orders

`cancelFuturesOrder(params)`

`cancelAllFuturesOrders(params)`

`cancelAllFuturesOrdersAfter(params)`

Querying Orders

`getFuturesAccountOrder(params)`

`getFuturesAccountOrderHistory(params)`

`getFuturesAccountOpenOrders(params?)`

`getFuturesAccountTrades(params)`

`getFuturesAccountTransactionHistory(params)`

Build docs developers (and LLMs) love

Spot (RestClient)

Futures (FuturesClientV2)

Earn & Sub-Accounts

WebSocket Reference

Documentation Index

​Setup

​Placing Orders

​submitFuturesOrder(params)

​updateFuturesLimitOrder(params)

​Cancelling Orders

​cancelFuturesOrder(params)

​cancelAllFuturesOrders(params)

​cancelAllFuturesOrdersAfter(params)

​Querying Orders

​getFuturesAccountOrder(params)

​getFuturesAccountOrderHistory(params)

​getFuturesAccountOpenOrders(params?)

​getFuturesAccountTrades(params)

​getFuturesAccountTransactionHistory(params)

Build docs developers (and LLMs) love

Setup

Placing Orders

`submitFuturesOrder(params)`

`updateFuturesLimitOrder(params)`

Cancelling Orders

`cancelFuturesOrder(params)`

`cancelAllFuturesOrders(params)`

`cancelAllFuturesOrdersAfter(params)`

Querying Orders

`getFuturesAccountOrder(params)`

`getFuturesAccountOrderHistory(params)`

`getFuturesAccountOpenOrders(params?)`

`getFuturesAccountTrades(params)`

`getFuturesAccountTransactionHistory(params)`