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 spot order management endpoints cover the full order lifecycle: placing single and batch orders, cancelling by ID or in bulk, and querying open orders, historical orders, and trade fills. All endpoints require authentication. Use the submitSpotOrderV2 method for standard spot orders and the V4 query endpoints for the most up-to-date order state.

​
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. Read-only keys cannot place or cancel orders.

​
Placing Orders

​
submitSpotOrderV2(params)

Places a single spot order. This is the primary endpoint for creating buy and sell orders. 
submitSpotOrderV2(params: SubmitSpotOrderV2Request): Promise<APIResponse<{ order_id: string }>>
​
symbol
string
required
Trading pair, e.g. "BTC_USDT".
​
side
string
required
Order direction: "buy" or "sell".
​
type
string
required
Order type. One of:
  • "limit" — execute at a specific price or better
  • "market" — execute immediately at the best available price
  • "limit_maker" — post-only limit order; rejected if it would immediately match
  • "ioc" — immediate-or-cancel; fills what it can, cancels the rest
​
size
string
Order quantity in base asset units. Required for limit, limit_maker, ioc orders, and market sell orders. For market buy orders, use notional instead.
​
price
string
Limit price. Required for limit, limit_maker, and ioc order types.
​
notional
string
Quote currency amount. Used for market buy orders (e.g. spend "100" USDT worth of BTC).
​
client_order_id
string
Optional user-defined order ID (max 32 characters). Must be unique per account.
​
stpmode
string
Self-trade prevention mode:
  • "none" (default) — no STP
  • "cancel_maker" — cancel the resting order
  • "cancel_taker" — cancel the incoming order
  • "cancel_both" — cancel both orders
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.submitSpotOrderV2({
  symbol: 'BTC_USDT',
  side: 'buy',
  type: 'limit',
  size: '0.001',
  price: '50000',
  client_order_id: 'my-order-001',
});

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

​
submitMarginOrderV1(params)

Places an order on an isolated margin account. Accepts the same parameters as submitSpotOrderV2. 
submitMarginOrderV1(params: SubmitSpotOrderV2Request): Promise<APIResponse<{ order_id: number }>>
The margin order endpoint returns order_id as a number, unlike the spot endpoint which returns it as a string.
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.submitMarginOrderV1({
  symbol: 'BTC_USDT',
  side: 'buy',
  type: 'limit',
  size: '0.001',
  price: '50000',
});

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

​
submitSpotBatchOrdersV4(params)

Places multiple orders for the same symbol in a single API call. Supports up to the exchange batch limit per request. 
submitSpotBatchOrdersV4(params: SubmitSpotBatchOrdersV4Request): Promise<
  APIResponse<{ orderIds: string[] }>
>
​
symbol
string
required
Trading pair for all orders in the batch, e.g. "BTC_USDT".
​
orderParams
array
required
Array of order objects. Each supports:
  • side ("buy" | "sell") — required
  • type ("limit" | "market" | "limit_maker" | "ioc") — required
  • size — quantity in base asset
  • price — limit price
  • notional — quote amount for market buys
  • clientOrderId — optional custom ID
  • stpmode — self-trade prevention
​
recvWindow
number
Request validity window in milliseconds (max 60000, default 5000).
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.submitSpotBatchOrdersV4({
  symbol: 'BTC_USDT',
  orderParams: [
    { side: 'buy', type: 'limit', size: '0.001', price: '49000', clientOrderId: 'batch-buy-1' },
    { side: 'buy', type: 'limit', size: '0.001', price: '48000', clientOrderId: 'batch-buy-2' },
    { side: 'sell', type: 'limit', size: '0.001', price: '52000', clientOrderId: 'batch-sell-1' },
  ],
});

console.log('Batch order IDs:', response.data.orderIds);

​
submitSpotBatchOrdersV2(params)

This method is marked @deprecated. Use submitSpotBatchOrdersV4 for new integrations.
Places a batch of spot orders using the legacy V2 endpoint. 
submitSpotBatchOrdersV2(params: {
  order_params: SubmitSpotOrderV2Request[];
}): Promise<APIResponse<{ responses: SubmittedSpotBatchOrderResponseV2[] }>>

​
Cancelling Orders

​
cancelSpotOrderV3(params)

Cancels a single spot order by order ID or client order ID. 
cancelSpotOrderV3(params: CancelOrdersV3Request): Promise<APIResponse<{ result: boolean }>>
​
symbol
string
required
Trading pair of the order to cancel.
​
order_id
string
Exchange-assigned order ID. Required if client_order_id is not provided.
​
client_order_id
string
User-defined order ID. Required if order_id is not provided.
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.cancelSpotOrderV3({
  symbol: 'BTC_USDT',
  order_id: '123456789',
});

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

​
cancelSpotBatchOrdersV4(params)

Cancels multiple orders for a symbol by providing arrays of order IDs or client order IDs. 
cancelSpotBatchOrdersV4(params: CancelSpotBatchOrdersV4Request): Promise<
  APIResponse<CancelSpotBatchOrdersV4Response>
>
​
symbol
string
required
Trading pair for the orders to cancel.
​
orderIds
string[]
Array of exchange order IDs to cancel.
​
clientOrderIds
string[]
Array of client order IDs to cancel.
​
recvWindow
number
Request validity window in milliseconds (max 60000).
Response — CancelSpotBatchOrdersV4Response fields:
FieldTypeDescription
successIdsstring[]Order IDs successfully cancelled
failIdsstring[]Order IDs that failed to cancel
totalCountnumberTotal orders attempted
successCountnumberNumber successfully cancelled
failedCountnumberNumber that failed
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.cancelSpotBatchOrdersV4({
  symbol: 'BTC_USDT',
  orderIds: ['111111', '222222', '333333'],
});

const result = response.data;
console.log(`Cancelled ${result.successCount}/${result.totalCount} orders`);
if (result.failedCount > 0) {
  console.log('Failed to cancel:', result.failIds);
}

​
cancelAllSpotOrders(params?)

Cancels all open spot orders, optionally filtered by symbol and/or side. 
cancelAllSpotOrders(params?: {
  symbol?: string;
  side?: OrderSide;
}): Promise<APIResponse<any>>
​
symbol
string
Optional. Cancel all orders for a specific trading pair only.
​
side
string
Optional. Cancel only "buy" or "sell" orders.
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 spot orders across all symbols
await client.cancelAllSpotOrders();
console.log('All open spot orders cancelled');

​
cancelSpotOrdersV1(params?)

This method is marked @deprecated. Use cancelAllSpotOrders or cancelSpotBatchOrdersV4 instead.
cancelSpotOrdersV1(params?: {
  symbol?: string;
  side?: OrderSide;
}): Promise<APIResponse<{}>>

​
Querying Orders

​
getSpotOrderByIdV4(params)

Retrieves the current state of an order by its exchange-assigned order ID. 
getSpotOrderByIdV4(params: SpotOrderByIdV4Request): Promise<APIResponse<SpotOrderV4>>
​
orderId
string
required
The exchange-assigned order ID.
​
queryState
string
Optional hint: "open" to query open orders only, "history" for filled/cancelled orders. Omit to query both.
​
recvwindow
number
Request validity window in milliseconds.
Response — SpotOrderV4 key fields:
FieldTypeDescription
orderIdstringExchange order ID
clientOrderIdstringClient-assigned order ID
symbolstringTrading pair
sidestring"buy" or "sell"
typestringOrder type
pricestringLimit price
sizestringRequested size
statestringOrder state (e.g. "new", "partially_filled", "filled", "cancelled")
priceAvgstringAverage fill price
filledSizestringAmount filled so far
filledNotionalstringQuote value filled
orderModestring"spot" or "iso_margin"
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.getSpotOrderByIdV4({
  orderId: '123456789',
});

const order = response.data;
console.log(`Order ${order.orderId}`);
console.log(`  State: ${order.state}`);
console.log(`  Filled: ${order.filledSize} / ${order.size}`);
console.log(`  Avg price: ${order.priceAvg}`);

​
getSpotOrderByClientOrderIdV4(params)

Retrieves an order using the client-assigned order ID set at submission time. 
getSpotOrderByClientOrderIdV4(params: SpotOrderByClientOrderIdV4Request): Promise<APIResponse<SpotOrderV4>>
​
clientOrderId
string
required
The client-assigned order ID.
​
queryState
string
Optional: "open" or "history".
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.getSpotOrderByClientOrderIdV4({
  clientOrderId: 'my-order-001',
});

console.log('State:', response.data.state);
console.log('Filled notional:', response.data.filledNotional);

​
getSpotOpenOrdersV4(params?)

Returns all currently open orders, optionally filtered by mode and time range. 
getSpotOpenOrdersV4(params?: SpotOpenOrdersV4Request): Promise<APIResponse<SpotOrderV4[]>>
​
orderMode
string
"spot" for spot orders, "iso_margin" for isolated margin orders.
​
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.getSpotOpenOrdersV4({ orderMode: 'spot' });
const orders = response.data;

console.log(`Open orders: ${orders.length}`);
for (const order of orders) {
  console.log(`  [${order.symbol}] ${order.side} ${order.size} @ ${order.price} — ${order.state}`);
}

​
getSpotHistoricOrdersV4(params?)

Returns order history (filled, cancelled, etc.) with optional filtering. 
getSpotHistoricOrdersV4(params?: SpotOrderTradeHistoryV4Request): Promise<APIResponse<SpotOrderV4[]>>
​
symbol
string
Optional. Filter to a specific trading pair.
​
orderMode
string
"spot" or "iso_margin".
​
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 oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;

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

for (const order of response.data) {
  console.log(`${order.orderId}: ${order.state} — filled ${order.filledSize}`);
}

​
getSpotAccountTradesV4(params?)

Returns a list of individual trade fills (executions) for your account. Each record corresponds to a partial or full fill event. 
getSpotAccountTradesV4(params?: SpotOrderTradeHistoryV4Request): Promise<APIResponse<SpotAccountTradeV4[]>>
​
symbol
string
Optional. Filter by trading pair.
​
orderMode
string
"spot" or "iso_margin".
​
startTime
number
Start of time range (ms).
​
endTime
number
End of time range (ms).
​
limit
number
Number of results, range [1, 200].
Response — SpotAccountTradeV4 additional fields (extends SpotOrderV4 base):
FieldTypeDescription
tradeIdstringUnique trade execution ID
feestringFee charged for this fill
feeCoinNamestringCurrency used for fee payment
tradeRole'taker' | 'maker'Whether order was taker or maker
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.getSpotAccountTradesV4({
  symbol: 'BTC_USDT',
  limit: 20,
});

for (const trade of response.data) {
  console.log(
    `[${trade.tradeId}] ${trade.side} ${trade.size} @ ${trade.price} ` +
    `| fee: ${trade.fee} ${trade.feeCoinName} (${trade.tradeRole})`
  );
}

​
getSpotAccountOrderTradesV4(params)

Returns all individual trade fills for a single specific order. Use this to get the complete fill breakdown when an order was partially or fully executed across multiple trades. 
getSpotAccountOrderTradesV4(params: {
  orderId: string;
  recvWindow?: number;
}): Promise<APIResponse<SpotAccountTradeV4[]>>
​
orderId
string
required
The exchange-assigned order ID to retrieve fills for.
​
recvWindow
number
Request validity window in milliseconds (max 60000, default 5000).
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.getSpotAccountOrderTradesV4({
  orderId: '123456789',
});

let totalFee = 0;
for (const trade of response.data) {
  console.log(
    `[${trade.tradeId}] ${trade.side} ${trade.size} @ ${trade.price} ` +
    `| fee: ${trade.fee} ${trade.feeCoinName} (${trade.tradeRole})`
  );
  totalFee += parseFloat(trade.fee);
}
console.log(`Total fees paid: ${totalFee}`);

​
Complete Order Lifecycle Example

The following example demonstrates the full lifecycle of a limit order: place it, poll its status, then cancel it if still open. 
import { RestClient } from 'bitmart-api';

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

  // Step 1: Place a limit buy order
  console.log('Placing limit buy order...');
  const submitResponse = await client.submitSpotOrderV2({
    symbol: 'BTC_USDT',
    side: 'buy',
    type: 'limit',
    size: '0.001',
    price: '45000',
    client_order_id: `order-${Date.now()}`,
  });

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

  // Step 2: Check order status
  console.log('\nChecking order status...');
  const statusResponse = await client.getSpotOrderByIdV4({
    orderId,
    queryState: 'open',
  });

  const order = statusResponse.data;
  console.log(`State: ${order.state}`);
  console.log(`Filled: ${order.filledSize} / ${order.size}`);
  console.log(`Price: ${order.price}`);

  // Step 3: Cancel if still open
  if (order.state === 'new' || order.state === 'partially_filled') {
    console.log('\nCancelling order...');
    const cancelResponse = await client.cancelSpotOrderV3({
      symbol: 'BTC_USDT',
      order_id: orderId,
    });
    console.log(`Cancel result: ${cancelResponse.data.result}`);
  } else {
    console.log(`\nOrder is already ${order.state} — no cancel needed.`);
  }

  // Step 4: Verify final state from history
  console.log('\nVerifying final state from history...');
  const finalState = await client.getSpotOrderByIdV4({
    orderId,
    queryState: 'history',
  });
  console.log('Final state:', finalState.data.state);
}

await orderLifecycle();
Use client_order_id when submitting orders so you can look them up by your own ID using getSpotOrderByClientOrderIdV4 — this is especially useful if you lose the exchange order_id before persisting it.

Build docs developers (and LLMs) love

Get started for freeTalk to us