Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/bybit-api/llms.txt
Use this file to discover all available pages before exploring further.
Trading endpoints require authentication — you must initialise RestClientV5 with a valid API key and secret. All order operations are gated behind the category parameter, which selects the market you want to trade.
import { RestClientV5 } from 'bybit-api';
const client = new RestClientV5({
key: process.env.API_KEY,
secret: process.env.API_SECRET,
});
The category Parameter
Every order method accepts a category field that selects which market segment the order is routed to:
| Value | Description |
|---|
'spot' | Spot trading (e.g. BTCUSDT) |
'linear' | USDT/USDC margined perpetuals and futures (e.g. BTCUSDT perp) |
'inverse' | Coin-margined (inverse) perpetuals and futures (e.g. BTCUSD) |
'option' | Options contracts (e.g. BTC-25DEC25-100000-C) |
Single Orders
submitOrder
Place a new order. The full OrderParamsV5 type covers all order configurations across all categories.
import { RestClientV5, OrderParamsV5 } from 'bybit-api';
const client = new RestClientV5({ key: '...', secret: '...' });
// Market buy
const marketOrder = await client.submitOrder({
category: 'linear',
symbol: 'BTCUSDT',
side: 'Buy', // 'Buy' | 'Sell'
orderType: 'Market', // 'Market' | 'Limit'
qty: '0.01',
});
// Limit sell with TP/SL
const limitOrder = await client.submitOrder({
category: 'linear',
symbol: 'BTCUSDT',
side: 'Sell',
orderType: 'Limit',
qty: '0.01',
price: '72000',
timeInForce: 'GTC', // 'GTC' | 'IOC' | 'FOK' | 'PostOnly' | 'RPI'
orderLinkId: 'my-order-1', // optional client order ID for idempotency
takeProfit: '68000',
stopLoss: '75000',
tpTriggerBy: 'MarkPrice', // 'LastPrice' | 'IndexPrice' | 'MarkPrice'
slTriggerBy: 'MarkPrice',
reduceOnly: false,
});
if (limitOrder.retCode === 0) {
console.log('Order placed:', limitOrder.result.orderId);
} else {
console.error(`Error ${limitOrder.retCode}: ${limitOrder.retMsg}`);
}
The orderLinkId field is your own unique client-side identifier for the order. Use it to correlate requests with Bybit order IDs and for idempotent retries.
Key OrderParamsV5 Fields
| Field | Type | Required | Description |
|---|
category | CategoryV5 | Yes | Market category |
symbol | string | Yes | Trading pair, e.g. 'BTCUSDT' |
side | 'Buy' | 'Sell' | Yes | Order direction |
orderType | 'Market' | 'Limit' | Yes | Execution type |
qty | string | Yes | Order quantity (base coin) |
price | string | Limit only | Limit price |
timeInForce | OrderTimeInForceV5 | No | 'GTC', 'IOC', 'FOK', 'PostOnly', 'RPI' |
orderLinkId | string | No | Client order ID (max 36 chars) |
takeProfit | string | No | TP trigger price |
stopLoss | string | No | SL trigger price |
reduceOnly | boolean | No | If true, only reduces an existing position |
positionIdx | PositionIdx | No | 0 = one-way mode, 1 = hedge Buy, 2 = hedge Sell |
amendOrder
Modify an existing open order’s price, quantity, or TP/SL. Either orderId or orderLinkId must be provided.
const amended = await client.amendOrder({
category: 'linear',
symbol: 'BTCUSDT',
orderId: '1234567890', // use orderId OR orderLinkId
price: '71500', // new limit price
qty: '0.02', // new quantity
takeProfit: '69000',
stopLoss: '74000',
});
cancelOrder
Cancel an open order by orderId or orderLinkId.
const cancelled = await client.cancelOrder({
category: 'linear',
symbol: 'BTCUSDT',
orderId: '1234567890',
});
Order Management
getActiveOrders
Query currently open (unfilled) orders.
const openOrders = await client.getActiveOrders({
category: 'linear',
symbol: 'BTCUSDT', // optional — omit for all symbols
limit: 50,
cursor: undefined,
});
openOrders.result.list.forEach((order) => {
console.log(order.orderId, order.side, order.price, order.qty, order.orderStatus);
});
cancelAllOrders
Cancel all open orders for a category, optionally filtered by symbol.
const result = await client.cancelAllOrders({
category: 'linear',
symbol: 'BTCUSDT', // optional — omit to cancel all across all symbols
});
console.log(`Cancelled ${result.result.list.length} orders`);
getHistoricOrders
Query completed or cancelled orders. Results are paginated.
const history = await client.getHistoricOrders({
category: 'linear',
symbol: 'BTCUSDT',
orderStatus: 'Filled', // optional filter
startTime: Date.now() - 7 * 24 * 60 * 60 * 1000,
endTime: Date.now(),
limit: 50,
cursor: undefined,
});
getExecutionList
Query trade execution (fill) history.
const executions = await client.getExecutionList({
category: 'linear',
symbol: 'BTCUSDT',
startTime: Date.now() - 24 * 60 * 60 * 1000,
limit: 100,
});
executions.result.list.forEach((fill) => {
console.log(fill.execTime, fill.execPrice, fill.execQty, fill.execFee);
});
Batch Orders
Batch endpoints let you submit up to 20 operations in a single HTTP request, reducing round-trip latency.
batchSubmitOrders
batchSubmitOrders takes the category as the first argument and an array of order objects as the second.
const batchResult = await client.batchSubmitOrders(
'linear',
[
{
symbol: 'BTCUSDT',
side: 'Buy',
orderType: 'Limit',
qty: '0.01',
price: '60000',
orderLinkId: 'batch-buy-1',
},
{
symbol: 'ETHUSDT',
side: 'Sell',
orderType: 'Limit',
qty: '0.1',
price: '4000',
orderLinkId: 'batch-sell-1',
},
],
);
// batchResult.result.list — per-order responses
// batchResult.retExtInfo.list — per-order error codes
batchResult.result.list.forEach((order, idx) => {
const ext = batchResult.retExtInfo.list[idx];
if (ext.code === 0) {
console.log(`Order ${order.orderLinkId} placed: ${order.orderId}`);
} else {
console.error(`Order ${order.orderLinkId} failed: ${ext.msg}`);
}
});
batchAmendOrders
const amended = await client.batchAmendOrders(
'linear',
[
{ symbol: 'BTCUSDT', orderId: '111', price: '61000' },
{ symbol: 'ETHUSDT', orderLinkId: 'batch-sell-1', price: '3950' },
],
);
batchCancelOrders
const cancelled = await client.batchCancelOrders(
'linear',
[
{ symbol: 'BTCUSDT', orderId: '111' },
{ symbol: 'ETHUSDT', orderLinkId: 'batch-sell-1' },
],
);
Strategy Orders
Strategy orders allow you to run automated execution algorithms such as TWAP, chase order, iceberg, and POV directly through the API.
createStrategyOrder
const strategy = await client.createStrategyOrder({
category: 'UTA_USDT', // StrategyCategoryV5: 'UTA_USDT' | 'UTA_USDC' | 'UTA_SPOT' | 'UTA_INVERSE' | ...
strategyType: 'twap', // 'twap' | 'chaseOrder' | 'iceberg' | 'pov'
symbol: 'BTCUSDT',
side: 'Buy',
size: '1', // total quantity in base coin (use size or positionValue)
duration: 3600, // total execution window in seconds (TWAP/POV)
interval: 60, // sub-order placement interval in seconds
});
getStrategyList
Query your list of active strategies.
const strategies = await client.getStrategyList({
category: 'UTA_USDT',
strategyType: 'twap',
});
getStrategyOrderList
Query individual child orders generated by a strategy. Requires the strategyId returned when the strategy was created.
const strategyOrders = await client.getStrategyOrderList({
strategyId: 'your-strategy-id',
});
stopStrategy
Stop a running strategy early.
await client.stopStrategy({
strategyId: 'your-strategy-id',
});
Disconnect Cancel All (DCP)
setDisconnectCancelAllWindow
Configure the DCP window. If the WebSocket connection drops and is not re-established within the configured window, all open orders are automatically cancelled. Only for institutional clients with options accounts.
await client.setDisconnectCancelAllWindow(
'option', // category — only 'option' is supported
10, // timeWindow in seconds (0 to disable, max 65)
);
Pre-Check Order
preCheckOrder
Validate an order against your account’s buying power and risk controls without actually placing it. Useful for verifying params before committing.
const check = await client.preCheckOrder({
category: 'linear',
symbol: 'BTCUSDT',
side: 'Buy',
orderType: 'Limit',
qty: '1',
price: '65000',
});
if (check.retCode === 0) {
console.log('Order would be accepted');
} else {
console.log('Pre-check failed:', check.retMsg);
}
Spread Trading
Spread trading lets you simultaneously manage two legs of a trade — for example, buying a near-dated contract while selling a far-dated one. Use getSpreadInstrumentsInfo to discover available spread symbols, then place orders via submitSpreadOrder.
getSpreadInstrumentsInfo
Fetch available spread instruments. Results are paginated via nextPageCursor.
const instruments = await client.getSpreadInstrumentsInfo({
baseCoin: 'BTC', // optional — filter by underlying
limit: 50,
cursor: undefined,
});
instruments.result.list.forEach((inst) => {
console.log(inst.symbol, inst.status);
});
submitSpreadOrder
Place a spread order. Unlike standard orders, spread orders do not use a category parameter.
const order = await client.submitSpreadOrder({
symbol: 'BTC-SPREAD-JUN-SEP', // spread symbol from getSpreadInstrumentsInfo
side: 'Buy', // 'Buy' | 'Sell'
orderType: 'Limit', // 'Limit' | 'Market'
qty: '0.01',
price: '200', // spread price (far leg minus near leg)
orderLinkId: 'spread-001', // required client order ID
timeInForce: 'GTC', // 'GTC' | 'IOC' | 'FOK' | 'PostOnly'
});
if (order.retCode === 0) {
console.log('Spread order ID:', order.result.orderId);
}
amendSpreadOrder
Modify the price or quantity of an open spread order.
await client.amendSpreadOrder({
orderId: order.result.orderId,
price: '210',
qty: '0.02',
});
cancelSpreadOrder
Cancel an open spread order by orderId or orderLinkId.
await client.cancelSpreadOrder({
orderId: order.result.orderId,
});
getSpreadOpenOrders
Query currently open spread orders.
const openOrders = await client.getSpreadOpenOrders({
symbol: 'BTC-SPREAD-JUN-SEP',
limit: 20,
});
getSpreadOrderHistory
Query historical (completed or cancelled) spread orders.
const history = await client.getSpreadOrderHistory({
baseCoin: 'BTC',
startTime: Date.now() - 7 * 24 * 60 * 60 * 1000,
limit: 50,
});
