Skip to main content
All account methods require authentication. Pass your apiKey, apiSecret, and apiPass when constructing the client.

​
Method reference

MethodHTTPEndpointDescription
getAccountInstruments(params)GET/api/v5/account/instrumentsInstruments available in your account
getBalance(params?)GET/api/v5/account/balanceUnified account balance
getPositions(params?)GET/api/v5/account/positionsOpen positions
getPositionsHistory(params?)GET/api/v5/account/positions-historyHistorical positions
getAccountPositionRisk(params?)GET/api/v5/account/account-position-riskPosition risk snapshot
getBills(params?)GET/api/v5/account/billsBills for last 7 days
getBillsArchive(params?)GET/api/v5/account/bills-archiveBills for last 3 months
getAccountConfiguration()GET/api/v5/account/configAccount-level configuration
setLeverage(params)POST/api/v5/account/set-leverageSet leverage for instrument or currency
getLeverage(params)GET/api/v5/account/leverage-infoCurrent leverage settings
getMaxBuySellAmount(params)GET/api/v5/account/max-sizeMax buy/sell quantity
getMaxAvailableTradableAmount(params)GET/api/v5/account/max-avail-sizeMax tradable amount
getFeeRates(params)GET/api/v5/account/trade-feeTrading fee tiers
getAccountRiskState()GET/api/v5/account/risk-stateAccount-level risk state
getGreeks(params?)GET/api/v5/account/greeksPortfolio greeks
getInterestAccrued(params?)GET/api/v5/account/interest-accruedAccrued interest
getInterestRate(params?)GET/api/v5/account/interest-rateInterest rates
getMaxWithdrawals(params?)GET/api/v5/account/max-withdrawalMax withdrawable amount
changePositionMargin(params)POST/api/v5/account/position/margin-balanceAdd or reduce isolated margin
setPositionMode(params)POST/api/v5/account/set-position-modeSwitch between net and long/short mode
setAccountMode(params)POST/api/v5/account/set-account-levelSet account level (simple, single, multi)
setAutoLoan(params)POST/api/v5/account/set-auto-loanEnable or disable auto loan
positionBuilder(params)POST/api/v5/account/position-builderSimulate portfolio margin scenarios

​
Examples

​
Get account balance

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 balances = await client.getBalance();
const usdtDetail = balances[0].details.find((d) => d.ccy === 'USDT');
console.log('USDT available:', usdtDetail?.availBal);
console.log('Total equity:', balances[0].totalEq);

​
Get open positions

import { RestClient } from 'okx-api';

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

// All open positions
const positions = await client.getPositions();

// Filter to SWAP positions only
const swapPositions = await client.getPositions({ instType: 'SWAP' });
for (const pos of swapPositions) {
  console.log(`${pos.instId}: size=${pos.pos}, PnL=${pos.unrealizedPnl}`);
}

​
Set leverage

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 result = await client.setLeverage({
  instId: 'BTC-USDT-SWAP',
  lever: '10',
  mgnMode: 'cross',
});
console.log('New leverage:', result[0].lever);

​
Get fee rates

const fees = await client.getFeeRates({
  instType: 'SPOT',
});
console.log('Maker fee:', fees[0].maker);
console.log('Taker fee:', fees[0].taker);

​
Query bills

// Last 7 days
const recentBills = await client.getBills({ ccy: 'USDT' });

// Last 3 months
const archiveBills = await client.getBillsArchive({ ccy: 'USDT' });

for (const bill of recentBills) {
  console.log(`${bill.type}: ${bill.balChg} ${bill.ccy} at ${bill.ts}`);
}

​
Request historical bill download

// Request a download link for Q1 2024 bills
const request = await client.requestBillsHistoryDownloadLink({
  year: '2024',
  quarter: 'Q1',
});

// Later, retrieve the generated link (may take up to 30–48 hours)
const link = await client.getRequestedBillsHistoryLink({
  year: '2024',
  quarter: 'Q1',
});
console.log('Download URL:', link[0]);

​
Key parameter types

interface SetLeverageRequest {
  instId?: string;       // Instrument ID (e.g. 'BTC-USDT-SWAP')
  ccy?: string;          // Currency for cross margin (e.g. 'BTC')
  lever: string;         // Leverage multiplier as a string (e.g. '10')
  mgnMode: 'cross' | 'isolated';
  posSide?: 'long' | 'short'; // Required in long/short position mode
}

interface GetPositionsParams {
  instType?: 'SPOT' | 'MARGIN' | 'SWAP' | 'FUTURES' | 'OPTION';
  instId?: string;  // Filter by instrument
  posId?: string;   // Filter by position ID
}

interface GetHistoricPositionParams {
  instType?: 'MARGIN' | 'SWAP' | 'FUTURES' | 'OPTION';
  instId?: string;
  mgnMode?: string;
  type?: string;
  posId?: string;
  after?: string;  // Unix ms timestamp — records older than this
  before?: string; // Unix ms timestamp — records newer than this
  limit?: string;  // Max 100, default 100
}

Build docs developers (and LLMs) love

Get started for freeTalk to us