Skip to main content
Spread trading lets you trade the price differential between two related instruments. Order placement and management require authentication; market data endpoints are public.

​
Method reference

​
Order management

MethodHTTPAuthEndpointDescription
submitSpreadOrder(params)POSTYes/api/v5/sprd/orderPlace a spread order
cancelSpreadOrder(params?)POSTYes/api/v5/sprd/cancel-orderCancel a spread order
cancelAllSpreadOrders(params?)POSTYes/api/v5/sprd/mass-cancelCancel all spread orders
updateSpreadOrder(params)POSTYes/api/v5/sprd/amend-orderAmend a spread order
cancelSpreadAllAfter(params)POSTYes/api/v5/sprd/cancel-all-afterCancel-all-after dead-man’s switch

​
Order queries

MethodHTTPAuthEndpointDescription
getSpreadOrder(params)GETYes/api/v5/sprd/orderDetails of a specific spread order
getSpreadActiveOrders(params?)GETYes/api/v5/sprd/orders-pendingActive (live) spread orders
getSpreadOrdersRecent(params?)GETYes/api/v5/sprd/orders-historyRecent spread order history
getSpreadOrdersArchive(params?)GETYes/api/v5/sprd/orders-history-archiveArchived spread order history
getSpreadTrades(params?)GETYes/api/v5/sprd/tradesYour spread trade fills

​
Market data (public)

MethodHTTPAuthEndpointDescription
getSpreads(params?)GETNo/api/v5/sprd/spreadsAvailable spread instruments
getSpreadOrderBook(params)GETNo/api/v5/sprd/booksOrder book for a spread
getSpreadTicker(params)GETNo/api/v5/market/sprd-tickerTicker for a spread
getSpreadPublicTrades(params?)GETNo/api/v5/sprd/public-tradesPublic spread trades
getSpreadCandles(params)GETNo/api/v5/market/sprd-candlesRecent candles for a spread
getSpreadHistoryCandles(params)GETNo/api/v5/market/sprd-history-candlesHistorical candles for a spread

​
Examples

​
Discover available spreads

import { RestClient } from 'okx-api';

const client = new RestClient(); // no auth needed

// All spreads
const spreads = await client.getSpreads();
for (const s of spreads.slice(0, 5)) {
  console.log(`Spread: ${s.sprdId} (${s.instId1} / ${s.instId2})`);
  console.log(`  Type: ${s.sprdType}, State: ${s.state}`);
}

// Filter by base instrument
const btcSpreads = await client.getSpreads({ baseCcy: 'BTC' });

​
Get spread market data

const client = new RestClient();

// Ticker
const [ticker] = await client.getSpreadTicker({ sprdId: 'BTC-USDT_BTC-USDT-SWAP' });
console.log('Spread last price:', ticker.last);
console.log('Spread bid/ask:', ticker.bidPx, '/', ticker.askPx);

// Order book
const [book] = await client.getSpreadOrderBook({
  sprdId: 'BTC-USDT_BTC-USDT-SWAP',
  sz: '5',
});
console.log('Best ask:', book.asks[0]);
console.log('Best bid:', book.bids[0]);

// Candles
const candles = await client.getSpreadCandles({
  sprdId: 'BTC-USDT_BTC-USDT-SWAP',
  bar: '1H',
  limit: '24',
});
console.log('Last 24 hourly candles:', candles.length);

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

const [order] = await client.submitSpreadOrder({
  sprdId: 'BTC-USDT_BTC-USDT-SWAP',
  side: 'buy',
  ordType: 'limit',
  sz: '1',
  px: '-50',  // spread price (can be negative)
});

console.log('Spread order ID:', order.ordId);

​
Amend and cancel spread orders

// Amend the price
const [amended] = await client.updateSpreadOrder({
  ordId: 'your-order-id',
  newPx: '-40',
  newSz: '2',
});
console.log('Amended:', amended.ordId);

// Cancel
const [cancelled] = await client.cancelSpreadOrder({
  ordId: 'your-order-id',
});
console.log('Cancelled:', cancelled.ordId);

// Cancel all
await client.cancelAllSpreadOrders();

​
Set cancel-all-after timer

// Cancel all spread orders if not refreshed within 60 seconds
await client.cancelSpreadAllAfter({ timeOut: '60' });

// Disable by setting to 0
await client.cancelSpreadAllAfter({ timeOut: '0' });

Build docs developers (and LLMs) love

Get started for freeTalk to us