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.

BitMart futures supports three categories of advanced conditional orders beyond simple limit and market orders. This page covers all three and their management methods. All methods require authentication (SIGNED).
When to use which order type:
  • Plan orders — trigger a new entry or exit order when the market price crosses a specified trigger price. Useful for breakout strategies or scheduled entries.
  • TP/SL orders — take-profit and stop-loss orders attached to an existing open position. They fire against position size automatically.
  • Trail orders — a trailing stop that dynamically follows price movement by a fixed callback rate, locking in profits as the market moves in your favour.

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

​
Plan Orders

Plan orders are trigger-based conditional orders. When the market price reaches the trigger_price, the exchange submits a limit or market order at the executive_price on your behalf.

​
submitFuturesPlanOrder(params)

Submits a new plan (trigger) order. Signature 
submitFuturesPlanOrder(params: SubmitFuturesPlanOrderRequest): Promise<
  APIResponse<{ order_id: number }>
>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
side
number
required
Order side:
  • 1 — buy_open_long
  • 2 — buy_close_short
  • 3 — sell_close_long
  • 4 — sell_open_short
​
trigger_price
string
required
The market price level that activates this order.
​
executive_price
string
The price at which the triggered order executes (required for limit type; omit for market).
​
price_way
number
required
Trigger direction: 1 = price rises to trigger, 2 = price falls to trigger.
​
price_type
number
required
Which price to compare against: 1 = last price, 2 = mark price.
​
size
number
required
Order quantity in contracts.
​
leverage
string
required
Leverage multiplier (e.g. "10").
​
open_type
string
required
Margin mode: cross or isolated.
​
type
string
Execution type: limit (default), market, take_profit, or stop_loss.
​
mode
number
Time-in-force: 1=GTC, 2=FOK, 3=IOC, 4=Post Only.
​
plan_category
number
Plan category: 1 = normal plan, 2 = position TP/SL plan.
​
preset_take_profit_price
string
Optional preset take-profit price to attach when the plan order triggers.
​
preset_stop_loss_price
string
Optional preset stop-loss price to attach when the plan order triggers.
import { FuturesClientV2 } from 'bitmart-api';

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

// Trigger a long entry when BTC breaks above $72,000
const plan = await client.submitFuturesPlanOrder({
  symbol: 'BTCUSDT',
  side: 1,                // buy_open_long
  type: 'limit',
  trigger_price: '72000',
  executive_price: '72050',
  price_way: 1,           // price rises to trigger
  price_type: 1,          // last price
  size: 1,
  leverage: '5',
  open_type: 'cross',
});

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

​
cancelFuturesPlanOrder(params)

Cancels a pending plan order by order ID or client order ID. Signature 
cancelFuturesPlanOrder(
  params: CancelFuturesPlanOrderRequest,
): Promise<APIResponse<any>>
​
symbol
string
required
Contract symbol.
​
order_id
string
Exchange plan 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.cancelFuturesPlanOrder({
  symbol: 'BTCUSDT',
  order_id: '123456789',
});

console.log('Plan order cancelled');

​
updateFuturesPlanOrder(params)

Modifies the trigger price and/or execution price of an existing pending plan order. Signature 
updateFuturesPlanOrder(params: UpdateFuturesPlanOrderRequest): Promise<
  APIResponse<{ order_id: string }>
>
​
symbol
string
required
Contract symbol.
​
order_id
string
Plan order ID to modify.
​
trigger_price
string
required
New trigger price.
​
executive_price
string
New execution price (for limit orders).
​
price_type
number
required
Price reference: 1 = last price, 2 = mark price.
​
type
string
required
Order type: limit or market.
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.updateFuturesPlanOrder({
  symbol: 'BTCUSDT',
  order_id: '123456789',
  trigger_price: '73000',    // Updated trigger
  executive_price: '73050',  // Updated execution price
  price_type: 1,
  type: 'limit',
});

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

​
updateFuturesPresetPlanOrder(params)

Modifies the preset take-profit and/or stop-loss prices attached to an existing plan order (set at submission time). Signature 
updateFuturesPresetPlanOrder(
  params: UpdateFuturesPresetPlanOrderRequest,
): Promise<APIResponse<{ order_id: string }>>
​
order_id
string
required
Plan order ID.
​
symbol
string
required
Contract symbol.
​
preset_take_profit_price
string
New take-profit price.
​
preset_stop_loss_price
string
New stop-loss price.
​
preset_take_profit_price_type
number
TP price type: 1 = last price, 2 = mark price.
​
preset_stop_loss_price_type
number
SL price type: 1 = last price, 2 = mark 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!,
});

await client.updateFuturesPresetPlanOrder({
  order_id: '123456789',
  symbol: 'BTCUSDT',
  preset_take_profit_price: '76000',
  preset_take_profit_price_type: 1,
  preset_stop_loss_price: '69000',
  preset_stop_loss_price_type: 1,
});

​
getFuturesAccountPlanOrders(params?)

Returns all currently active plan orders. Signature 
getFuturesAccountPlanOrders(
  params?: FuturesAccountPlanOrdersRequest,
): Promise<APIResponse<FuturesAccountPlanOrders[]>>
​
symbol
string
Filter by contract symbol.
​
type
string
Filter by execution type: limit or market.
​
limit
number
Maximum results to return.
​
plan_type
string
Filter by plan category: plan (normal) or profit_loss (TP/SL plan).
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 planOrders = await client.getFuturesAccountPlanOrders({
  symbol: 'BTCUSDT',
  plan_type: 'plan',
});

for (const order of planOrders.data) {
  console.log(`Plan ${order.order_id}: trigger=${order.trigger_price}, exec=${order.executive_price}`);
}

​
Take-Profit / Stop-Loss Orders

TP/SL orders are position-level conditional orders that execute against an existing open position when the trigger price is reached. They differ from plan orders in that they are attached to a position rather than opening a new one.
side for TP/SL orders is limited to 2 (buy_close_short — close a short) or 3 (sell_close_long — close a long), since TP/SL orders always close existing positions.

​
submitFuturesTPSLOrder(params)

Submits a take-profit or stop-loss order against an open position. Signature 
submitFuturesTPSLOrder(params: SubmitFuturesTPSLOrderRequest): Promise<
  APIResponse<{
    order_id: string;
    client_order_id?: string;
  }>
>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
type
string
required
Order type: take_profit or stop_loss.
​
side
number
required
Close side: 2 (buy_close_short) or 3 (sell_close_long).
​
trigger_price
string
required
The market price at which this order activates.
​
executive_price
string
required
The price at which the order executes once triggered (for limit execution).
​
price_type
number
required
Reference price for trigger: 1 = last price, 2 = mark price.
​
size
number
Quantity to close in contracts. Omit to close the entire position.
​
plan_category
number
Plan category: 1 = position TP/SL, 2 = preset TP/SL on plan order.
​
client_order_id
string
Optional client-defined ID.
​
category
string
Execution category: limit or market.
import { FuturesClientV2 } from 'bitmart-api';

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

// Take profit: close long when price reaches $75,000
const tp = await client.submitFuturesTPSLOrder({
  symbol: 'BTCUSDT',
  type: 'take_profit',
  side: 3,              // sell_close_long
  trigger_price: '75000',
  executive_price: '74950',
  price_type: 2,        // mark price
  plan_category: 1,
  category: 'limit',
});

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

​
updateFuturesTPSLOrder(params)

Modifies the trigger price and/or execution price of an existing TP/SL order. Signature 
updateFuturesTPSLOrder(params: UpdateFuturesTPSLOrderRequest): Promise<
  APIResponse<{ order_id: string }>
>
​
symbol
string
required
Contract symbol.
​
order_id
string
TP/SL order ID to modify.
​
client_order_id
string
Client order ID to modify.
​
trigger_price
string
required
New trigger price.
​
executive_price
string
New execution price.
​
price_type
number
required
Reference price: 1 = last price, 2 = mark price.
​
plan_category
number
Plan category: 1 or 2.
​
category
string
Execution type: limit or market.
import { FuturesClientV2 } from 'bitmart-api';

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

// Move take-profit up as the market rises
const result = await client.updateFuturesTPSLOrder({
  symbol: 'BTCUSDT',
  order_id: '987654321',
  trigger_price: '78000',    // New TP trigger
  executive_price: '77950',  // New execution price
  price_type: 2,
  plan_category: 1,
  category: 'limit',
});

console.log('Updated TP/SL order:', result.data.order_id);

​
Trailing Stop Orders

Trail orders follow the market at a fixed percentage distance (callback_rate). As price moves in your favour, the stop price trails automatically. If price reverses by the callback_rate, the order triggers and closes your position.

​
submitFuturesTrailOrder(params)

Submits a trailing stop order. Signature 
submitFuturesTrailOrder(params: SubmitFuturesTrailOrderRequest): Promise<
  APIResponse<{ order_id: number }>
>
​
symbol
string
required
Contract symbol (e.g. BTCUSDT).
​
side
number
required
Order side (1–4, same values as standard orders).
​
leverage
string
required
Leverage multiplier.
​
open_type
string
required
Margin mode: cross or isolated.
​
size
number
required
Order quantity in contracts.
​
activation_price
string
required
Price at which trailing starts. The trailing stop does not activate until this price is reached.
​
callback_rate
string
required
Trailing callback percentage (e.g. "1.5" for 1.5%). The order triggers when price reverses by this percentage from its peak/trough.
​
activation_price_type
number
required
Reference price for activation: 1 = last price, 2 = mark price.
Trail orders combine an activation price with a callback rate. The stop does not activate until activation_price is reached, then trails by callback_rate. This avoids premature triggering on entry volatility.
import { FuturesClientV2 } from 'bitmart-api';

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

// Trail: activates when BTC hits $72,000, then trails 2% below peak
const trailOrder = await client.submitFuturesTrailOrder({
  symbol: 'BTCUSDT',
  side: 3,                     // sell_close_long
  leverage: '5',
  open_type: 'cross',
  size: 1,
  activation_price: '72000',   // Start trailing at $72K
  callback_rate: '2.0',        // Trigger if drops 2% from peak
  activation_price_type: 2,    // mark price
});

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

​
cancelFuturesTrailOrder(params)

Cancels an active trailing stop order. Signature 
cancelFuturesTrailOrder(
  params: CancelFuturesTrailOrderRequest,
): Promise<APIResponse<any>>
​
symbol
string
required
Contract symbol.
​
order_id
string
Trail 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.cancelFuturesTrailOrder({
  symbol: 'BTCUSDT',
  order_id: '112233445',
});

console.log('Trail order cancelled');

​
Order Type Comparison

Use this table to choose the right conditional order type for your strategy:
TypeTriggerCloses existing position?Use case
Plan orderPrice levelNo (opens new order)Breakout entry, scaled entries
TP/SL orderPrice levelYes (position-level)Risk management on open positions
Trail orderPrice level + callback rateYes (closes position)Lock in profits on trending moves

Build docs developers (and LLMs) love

Get started for freeTalk to us