Skip to main content
All trading methods require authentication.

​
Method reference

​
Order management

MethodHTTPEndpointDescription
submitOrder(params)POST/api/v5/trade/orderPlace a single order
submitMultipleOrders(params[])POST/api/v5/trade/batch-ordersPlace up to 20 orders in one call
cancelOrder(params)POST/api/v5/trade/cancel-orderCancel a single order
cancelMultipleOrders(params[])POST/api/v5/trade/cancel-batch-ordersCancel up to 20 orders in one call
amendOrder(params)POST/api/v5/trade/amend-orderAmend price or size of a live order
amendMultipleOrders(params[])POST/api/v5/trade/amend-batch-ordersAmend up to 20 orders in one call
closePositions(params)POST/api/v5/trade/close-positionMarket-close an entire position
cancelAllAfter(params)POST/api/v5/trade/cancel-all-afterDead-man’s switch — cancel all orders after timeout
cancelMassOrder(params)POST/api/v5/trade/mass-cancelCancel all orders for an instrument family

​
Order queries

MethodHTTPEndpointDescription
getOrderDetails(params)GET/api/v5/trade/orderDetails of a specific order
getOrderList(params?)GET/api/v5/trade/orders-pendingAll pending (live) orders
getOrderHistory(params)GET/api/v5/trade/orders-historyCompleted orders — last 7 days
getOrderHistoryArchive(params)GET/api/v5/trade/orders-history-archiveCompleted orders — last 3 months
getFills(params?)GET/api/v5/trade/fillsTrade fills — last 7 days
getFillsHistory(params)GET/api/v5/trade/fills-historyTrade fills — last 3 months
getAccountRateLimit()GET/api/v5/trade/account-rate-limitCurrent order rate limit usage

​
Algo orders

MethodHTTPEndpointDescription
placeAlgoOrder(params)POST/api/v5/trade/order-algoPlace a stop/trigger/iceberg/twap order
cancelAlgoOrder(params[])POST/api/v5/trade/cancel-algosCancel pending algo orders
amendAlgoOrder(params)POST/api/v5/trade/amend-algosAmend a pending algo order
cancelAdvanceAlgoOrder(params[])POST/api/v5/trade/cancel-advance-algosCancel advanced (iceberg/twap) algo orders
getAlgoOrderDetails(params)GET/api/v5/trade/order-algoDetails of an algo order
getAlgoOrderList(params)GET/api/v5/trade/orders-algo-pendingPending algo orders
getAlgoOrderHistory(params)GET/api/v5/trade/orders-algo-historyHistorical algo orders

​
Examples

​
Place a market buy order

import { RestClient } from 'okx-api';

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

// Market buy: spend 100 USDT to buy BTC
const result = await client.submitOrder({
  instId: 'BTC-USDT',
  tdMode: 'cash',
  side: 'buy',
  ordType: 'market',
  sz: '100',       // quantity in quote currency when tgtCcy = 'base_ccy'
  tgtCcy: 'base_ccy',
});

console.log('Order ID:', result[0].ordId);
console.log('Client order ID:', result[0].clOrdId);

​
Place a limit sell order

const result = await client.submitOrder({
  instId: 'BTC-USDT',
  tdMode: 'cash',
  side: 'sell',
  ordType: 'limit',
  sz: '0.001',   // sell 0.001 BTC
  px: '70000',   // at $70,000
});
console.log('Order placed:', result[0].ordId);

​
Full workflow: place an order and check its status

import { RestClient } from 'okx-api';

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

async function placeAndTrack() {
  // 1. Place a limit buy
  const [order] = await client.submitOrder({
    instId: 'ETH-USDT',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'limit',
    sz: '0.1',
    px: '3000',
  });

  console.log('Placed order:', order.ordId);

  // 2. Poll for its status
  const [details] = await client.getOrderDetails({
    instId: 'ETH-USDT',
    ordId: order.ordId,
  });

  console.log('State:', details.state);        // 'live', 'filled', 'canceled'
  console.log('Filled size:', details.fillSz);
  console.log('Average fill price:', details.avgPx);

  // 3. Cancel if still live
  if (details.state === 'live') {
    const [cancelled] = await client.cancelOrder({
      instId: 'ETH-USDT',
      ordId: order.ordId,
    });
    console.log('Cancelled:', cancelled.ordId);
  }
}

placeAndTrack().catch(console.error);

​
Batch order placement

const results = await client.submitMultipleOrders([
  {
    instId: 'BTC-USDT',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'limit',
    sz: '0.001',
    px: '60000',
  },
  {
    instId: 'ETH-USDT',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'limit',
    sz: '0.1',
    px: '3000',
  },
]);

for (const r of results) {
  if (r.sCode === '0') {
    console.log('OK:', r.ordId);
  } else {
    console.error('Failed:', r.sMsg);
  }
}

​
Place a stop-loss algo order

const algoResult = await client.placeAlgoOrder({
  instId: 'BTC-USDT-SWAP',
  tdMode: 'cross',
  side: 'sell',
  ordType: 'conditional',
  sz: '1',
  slTriggerPx: '55000',   // trigger price
  slOrdPx: '-1',          // -1 = market order on trigger
  slTriggerPxType: 'last',
});
console.log('Algo order ID:', algoResult[0].algoId);

​
Cancel all orders after a timeout (dead-man’s switch)

// Cancel all orders if not refreshed within 60 seconds
const response = await client.cancelAllAfter({ timeOut: '60' });
console.log('Trigger time:', response[0].triggerTime);

// To disable, set timeOut to '0'
await client.cancelAllAfter({ timeOut: '0' });

​
Key parameter types

interface OrderRequest {
  instId: string;                          // e.g. 'BTC-USDT'
  tdMode: 'cash' | 'cross' | 'isolated';  // trade mode
  side: 'buy' | 'sell';
  ordType: 'market' | 'limit' | 'post_only' | 'fok' | 'ioc' | 'optimal_limit_ioc';
  sz: string;                              // quantity
  px?: string;                             // price (required for limit orders)
  ccy?: string;                            // margin currency
  clOrdId?: string;                        // client order ID
  tag?: string;                            // order tag
  posSide?: 'long' | 'short' | 'net';
  tgtCcy?: 'base_ccy' | 'quote_ccy';      // which currency sz is denominated in
  reduceOnly?: boolean;
  tpTriggerPx?: string;                    // take-profit trigger price
  tpOrdPx?: string;                        // take-profit order price
  slTriggerPx?: string;                    // stop-loss trigger price
  slOrdPx?: string;                        // stop-loss order price
}

interface OrderIdRequest {
  instId?: string;   // Instrument ID
  ordId?: string;    // Exchange order ID
  clOrdId?: string;  // Client order ID (alternative to ordId)
}

interface AmendOrderRequest {
  instId: string;
  ordId?: string;
  clOrdId?: string;
  reqId?: string;      // Client request ID for tracking the amendment
  newSz?: string;      // New quantity
  newPx?: string;      // New price
  cxlOnFail?: boolean; // Cancel the order if amendment fails
}

interface OrderHistoryRequest {
  instType: 'SPOT' | 'MARGIN' | 'SWAP' | 'FUTURES' | 'OPTION';
  instId?: string;
  ordType?: string;
  state?: string;
  after?: string;  // Unix ms — records older than this
  before?: string; // Unix ms — records newer than this
  limit?: string;  // Max 100
}

Build docs developers (and LLMs) love

Get started for freeTalk to us