Method reference
Order management
| Method | HTTP | Endpoint | Description |
|---|---|---|---|
submitOrder(params) | POST | /api/v5/trade/order | Place a single order |
submitMultipleOrders(params[]) | POST | /api/v5/trade/batch-orders | Place up to 20 orders in one call |
cancelOrder(params) | POST | /api/v5/trade/cancel-order | Cancel a single order |
cancelMultipleOrders(params[]) | POST | /api/v5/trade/cancel-batch-orders | Cancel up to 20 orders in one call |
amendOrder(params) | POST | /api/v5/trade/amend-order | Amend price or size of a live order |
amendMultipleOrders(params[]) | POST | /api/v5/trade/amend-batch-orders | Amend up to 20 orders in one call |
closePositions(params) | POST | /api/v5/trade/close-position | Market-close an entire position |
cancelAllAfter(params) | POST | /api/v5/trade/cancel-all-after | Dead-man’s switch — cancel all orders after timeout |
cancelMassOrder(params) | POST | /api/v5/trade/mass-cancel | Cancel all orders for an instrument family |
Order queries
| Method | HTTP | Endpoint | Description |
|---|---|---|---|
getOrderDetails(params) | GET | /api/v5/trade/order | Details of a specific order |
getOrderList(params?) | GET | /api/v5/trade/orders-pending | All pending (live) orders |
getOrderHistory(params) | GET | /api/v5/trade/orders-history | Completed orders — last 7 days |
getOrderHistoryArchive(params) | GET | /api/v5/trade/orders-history-archive | Completed orders — last 3 months |
getFills(params?) | GET | /api/v5/trade/fills | Trade fills — last 7 days |
getFillsHistory(params) | GET | /api/v5/trade/fills-history | Trade fills — last 3 months |
getAccountRateLimit() | GET | /api/v5/trade/account-rate-limit | Current order rate limit usage |
Algo orders
| Method | HTTP | Endpoint | Description |
|---|---|---|---|
placeAlgoOrder(params) | POST | /api/v5/trade/order-algo | Place a stop/trigger/iceberg/twap order |
cancelAlgoOrder(params[]) | POST | /api/v5/trade/cancel-algos | Cancel pending algo orders |
amendAlgoOrder(params) | POST | /api/v5/trade/amend-algos | Amend a pending algo order |
cancelAdvanceAlgoOrder(params[]) | POST | /api/v5/trade/cancel-advance-algos | Cancel advanced (iceberg/twap) algo orders |
getAlgoOrderDetails(params) | GET | /api/v5/trade/order-algo | Details of an algo order |
getAlgoOrderList(params) | GET | /api/v5/trade/orders-algo-pending | Pending algo orders |
getAlgoOrderHistory(params) | GET | /api/v5/trade/orders-algo-history | Historical 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
OrderRequest
OrderRequest
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
}
OrderIdRequest
OrderIdRequest
interface OrderIdRequest {
instId?: string; // Instrument ID
ordId?: string; // Exchange order ID
clOrdId?: string; // Client order ID (alternative to ordId)
}
AmendOrderRequest
AmendOrderRequest
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
}
OrderHistoryRequest
OrderHistoryRequest
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
}