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’s spot algo order system lets you automate conditional execution without running your own monitoring loop. Two algo order types are supported: trigger orders (execute a market or limit order when a price condition is met) and TP/SL orders (take-profit / stop-loss pairs). All algo endpoints use the V4 API and require full authentication. This page also covers the getBrokerRebate method for API broker integrations.

​
Setup

import { RestClient } from 'bitmart-api';

const client = new RestClient({
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  apiMemo: 'YOUR_API_MEMO',
});
All methods on this page require a valid API key with trade permissions enabled.

​
Algo Order Types

A trigger order monitors the market and submits a new limit or market order once the spot price crosses a specified trigger_price.Use case: “Buy 0.1 BTC with a market order if the price drops to 45,000 USDT.”Key fields:
  • type: "trigger"
  • trigger_price — the price level to watch
  • trigger_type — "limit" (trigger at exact price) or "market" (trigger at market price)
  • price — the execution price for a limit trigger order
  • size or notional — order quantity

​
Placing Algo Orders

​
submitSpotAlgoOrderV4(params)

Submits a new spot algo order (trigger or TP/SL). 
submitSpotAlgoOrderV4(params: SubmitSpotAlgoOrderV4Request): Promise<APIResponse<{ order_id: string }>>
​
symbol
string
required
Trading pair, e.g. "BTC_USDT".
​
side
string
required
"buy" or "sell".
​
type
string
required
Algo order type: "trigger" or "tp/sl".
​
trigger_price
string
The price at which the algo order activates. Required for trigger and TP/SL orders.
​
trigger_type
string
Execution type when triggered: "limit" (execute at price) or "market" (execute at best market price).
​
price
string
Execution limit price. Required when trigger_type is "limit".
​
size
string
Order quantity in base asset units. Use for sell orders and limit-triggered buy orders.
​
notional
string
Quote currency amount. Used for market-triggered buy orders (e.g. spend "200" USDT).
​
client_order_id
string
Optional user-defined order ID (max 32 characters, must be unique per account).
import { RestClient } from 'bitmart-api';

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

// Buy 0.01 BTC at market price when BTC drops to 45,000 USDT
const response = await client.submitSpotAlgoOrderV4({
  symbol: 'BTC_USDT',
  side: 'buy',
  type: 'trigger',
  trigger_price: '45000',
  trigger_type: 'market',
  size: '0.01',
  client_order_id: `trigger-buy-${Date.now()}`,
});

console.log('Trigger order placed! ID:', response.data.order_id);

​
Cancelling Algo Orders

​
cancelSpotAlgoOrderV4(params)

Cancels a single open algo order by its order ID. 
cancelSpotAlgoOrderV4(params: CancelSpotAlgoOrderV4Request): Promise<APIResponse<{ result: boolean }>>
​
symbol
string
required
Trading pair of the algo order.
​
order_id
string
required
The exchange-assigned algo order ID to cancel.
​
type
string
required
The algo order type: "tp/sl" or "trigger". Must match the type used at submission.
import { RestClient } from 'bitmart-api';

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

const response = await client.cancelSpotAlgoOrderV4({
  symbol: 'BTC_USDT',
  order_id: '987654321',
  type: 'trigger',
});

console.log('Cancel result:', response.data.result);

​
cancelAllSpotAlgoOrdersV4(params)

Cancels all open algo orders of a specific type, optionally filtered to one symbol. 
cancelAllSpotAlgoOrdersV4(params: CancelAllSpotAlgoOrdersV4Request): Promise<APIResponse<{}>>
​
type
string
required
Algo type to cancel: "tp/sl" or "trigger".
​
symbol
string
Optional. Cancel only algo orders for this trading pair. If omitted, cancels all symbols.
import { RestClient } from 'bitmart-api';

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

// Cancel all open trigger orders on BTC_USDT
await client.cancelAllSpotAlgoOrdersV4({
  symbol: 'BTC_USDT',
  type: 'trigger',
});

console.log('All BTC_USDT trigger orders cancelled');

​
Querying Algo Orders

​
getSpotAlgoOrderByIdV4(params)

Returns the details of a single algo order by its exchange order ID. 
getSpotAlgoOrderByIdV4(params: SpotAlgoOrderByIdV4Request): Promise<APIResponse<SpotAlgoOrderV4>>
​
orderId
string
required
The exchange-assigned algo order ID.
​
queryState
string
Hint to speed up the lookup: "open" or "history".
​
recvWindow
number
Request validity window in milliseconds.
Response — SpotAlgoOrderV4 fields:
FieldTypeDescription
orderIdstringExchange algo order ID
clientOrderIdstringClient-assigned ID
symbolstringTrading pair
sidestring"buy" or "sell"
orderModestringOrder mode identifier
trigger_typestring"limit" or "market"
statestringCurrent state (e.g. "active", "triggered", "cancelled")
cancelSourcestringReason for cancellation (if applicable)
pricestringExecution price (for limit triggers)
sizestringOrder size
notionalstringQuote amount (for notional-based orders)
createTimenumberCreation timestamp (ms)
updateTimenumberLast update timestamp (ms)
import { RestClient } from 'bitmart-api';

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

const response = await client.getSpotAlgoOrderByIdV4({
  orderId: '987654321',
  queryState: 'open',
});

const order = response.data;
console.log(`Algo Order ${order.orderId}`);
console.log(`  Symbol: ${order.symbol}`);
console.log(`  Side: ${order.side}`);
console.log(`  State: ${order.state}`);
console.log(`  Trigger type: ${order.trigger_type}`);
console.log(`  Size: ${order.size}`);

​
getSpotAlgoOrderByClientOrderIdV4(params)

Retrieves an algo order using the client-assigned order ID provided at submission. 
getSpotAlgoOrderByClientOrderIdV4(params: SpotAlgoOrderByClientOrderIdV4Request): Promise<APIResponse<SpotAlgoOrderV4>>
​
clientOrderId
string
required
The client-assigned order ID.
​
queryState
string
Optional: "open" or "history".
​
recvWindow
number
Request validity window in milliseconds.
import { RestClient } from 'bitmart-api';

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

const response = await client.getSpotAlgoOrderByClientOrderIdV4({
  clientOrderId: 'trigger-buy-1703001234567',
});

console.log('State:', response.data.state);
console.log('Trigger type:', response.data.trigger_type);

​
getSpotAlgoOpenOrdersV4(params?)

Returns all currently active (open) algo orders. 
getSpotAlgoOpenOrdersV4(params?: SpotAlgoOpenOrdersV4Request): Promise<APIResponse<SpotAlgoOrderV4[]>>
​
symbol
string
Optional. Filter to a specific trading pair.
​
orderMode
string
Filter by algo type: "trigger" or "tp/sl".
​
startTime
number
Filter by creation time start (ms).
​
endTime
number
Filter by creation time end (ms).
​
limit
number
Number of results, range [1, 200], default 200.
​
recvWindow
number
Request validity window in milliseconds.
import { RestClient } from 'bitmart-api';

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

const response = await client.getSpotAlgoOpenOrdersV4();
console.log(`Open algo orders: ${response.data.length}`);

for (const order of response.data) {
  console.log(
    `[${order.symbol}] ${order.side} ${order.size} | ` +
    `state: ${order.state} | trigger: ${order.trigger_type}`
  );
}

​
getSpotAlgoHistoryOrdersV4(params?)

Returns historical algo orders (triggered, cancelled, expired). 
getSpotAlgoHistoryOrdersV4(params?: SpotAlgoHistoryOrdersV4Request): Promise<APIResponse<SpotAlgoOrderV4[]>>
​
symbol
string
Optional. Filter by trading pair.
​
orderMode
string
"trigger" or "tp/sl".
​
startTime
number
Start of time range (ms).
​
endTime
number
End of time range (ms).
​
limit
number
Number of results, range [1, 200], default 200.
​
recvWindow
number
Request validity window in milliseconds.
import { RestClient } from 'bitmart-api';

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

const oneWeekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;

const response = await client.getSpotAlgoHistoryOrdersV4({
  symbol: 'BTC_USDT',
  startTime: oneWeekAgo,
  limit: 50,
});

for (const order of response.data) {
  console.log(
    `[${new Date(order.createTime).toISOString()}] ${order.side} ${order.size} — ${order.state}`
  );
}

​
Broker Rebate

​
getBrokerRebate(params?)

Returns rebate records for API broker accounts. Only applicable if your API key is associated with a registered BitMart broker program. 
getBrokerRebate(params?: SpotBrokerRebateRequest): Promise<APIResponse<SpotBrokerRebateResult>>
​
start_time
number
Optional. Start of the query range as a Unix timestamp in seconds.
​
end_time
number
Optional. End of the query range as a Unix timestamp in seconds.
Response — SpotBrokerRebateResult structure: 
interface SpotBrokerRebateResult {
  rebates: {
    [date: string]: SpotBrokerRebateRow[];
  };
}

interface SpotBrokerRebateRow {
  currency: string;       // Currency of the rebate
  rebate_amount: string;  // Rebate amount for that day
}
This endpoint is only available to accounts enrolled in the BitMart broker program. Standard API keys will receive an authorization error.
import { RestClient } from 'bitmart-api';

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

const now = Math.floor(Date.now() / 1000);
const thirtyDaysAgo = now - 30 * 24 * 60 * 60;

const response = await client.getBrokerRebate({
  start_time: thirtyDaysAgo,
  end_time: now,
});

const { rebates } = response.data;
for (const [date, rows] of Object.entries(rebates)) {
  for (const row of rows) {
    console.log(`${date}: ${row.rebate_amount} ${row.currency}`);
  }
}

​
Complete Algo Order Lifecycle Example

This example shows how to submit a trigger order, monitor it until it activates or times out, and cancel it if needed. 
import { RestClient } from 'bitmart-api';

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

  const clientOrderId = `algo-${Date.now()}`;

  // Step 1: Place a trigger buy order
  console.log('Placing trigger buy order...');
  const submitResponse = await client.submitSpotAlgoOrderV4({
    symbol: 'BTC_USDT',
    side: 'buy',
    type: 'trigger',
    trigger_price: '45000',
    trigger_type: 'market',
    size: '0.001',
    client_order_id: clientOrderId,
  });

  const orderId = submitResponse.data.order_id;
  console.log(`Algo order placed: ${orderId}`);

  // Step 2: Verify it's active
  const orderDetail = await client.getSpotAlgoOrderByClientOrderIdV4({
    clientOrderId,
    queryState: 'open',
  });
  console.log(`Current state: ${orderDetail.data.state}`);

  // Step 3: List all open trigger orders
  const openOrders = await client.getSpotAlgoOpenOrdersV4({
    symbol: 'BTC_USDT',
    orderMode: 'trigger',
  });
  console.log(`Open trigger orders on BTC_USDT: ${openOrders.data.length}`);

  // Step 4: Cancel if the trigger condition is no longer relevant
  const cancelResponse = await client.cancelSpotAlgoOrderV4({
    symbol: 'BTC_USDT',
    order_id: orderId,
    type: 'trigger',
  });
  console.log(`Cancelled: ${cancelResponse.data.result}`);

  // Step 5: Confirm it appears in history
  const history = await client.getSpotAlgoHistoryOrdersV4({
    symbol: 'BTC_USDT',
    limit: 5,
  });
  const cancelled = history.data.find((o) => o.orderId === orderId);
  console.log(`Final state in history: ${cancelled?.state ?? 'not found yet'}`);
}

await algoOrderLifecycle();
Always persist the order_id returned by submitSpotAlgoOrderV4 immediately. If your process restarts, you can recover the order via getSpotAlgoOrderByClientOrderIdV4 using the client_order_id you supplied at creation.

Build docs developers (and LLMs) love

Get started for freeTalk to us