A Complete Guide to OKX's API v5

Introduction

This technical guide provides a comprehensive overview of trading with OKX API v5, the latest version designed to support OKX’s Unified Account trading system. Whether you’re a developer integrating the API or a trader leveraging automated strategies, this guide covers essential updates, configurations, and trading workflows.

Key Changes in API v5

Unified API Across Products

Unlike previous versions, API v5 consolidates endpoints for different financial instruments (spot, futures, swaps, options). For example, placing orders uses a single endpoint:

POST /api/v5/trade/order

This simplifies integration by eliminating the need for separate API models per product.

Streamlined Naming Conventions

Field names now use camelCase with abbreviations to optimize bandwidth:

| Field | V5 API | V3 API |
|---------------------|---------|---------------------|
| Currency | ccy | currency |
| Instrument ID | instId| instrument_id |
| Underlying | uly | underlying |
| Unrealized PnL | upl | unrealized_pnl |

Enhanced WebSocket Efficiency

Standard Compression: Uses Per-Message Deflate (enable via permessage-deflate in headers).
Channel Separation:
- Public: Tickers, candles (no login required).
- Private: Account, positions (requires authentication).

WebSocket Order Placement

Orders can now be placed/amended/canceled directly via WebSocket, reducing latency vs. REST.

Authentication Updates

REST: Same as v3 (signature in headers).

WebSocket: Login request format changed to key-value pairs:

{  
  "op": "login",  
  "args": [{  
    "apiKey": "YOUR_KEY",  
    "passphrase": "YOUR_PASSPHRASE",  
    "timestamp": "TIMESTAMP",  
    "sign": "SIGNATURE"  
  }]  
}

Sub-Account API Key Management

Master accounts can CRUD sub-account API keys:

| Action | Endpoint |
|---------|-----------------------------------------|
| Create | POST /api/v5/users/subaccount/apikey |
| Read | GET /api/v5/users/subaccount/apikey |
| Update | POST /api/v5/users/subaccount/modify-apikey |
| Delete | POST /api/v5/users/subaccount/delete-apikey |

👉 Best practices for API security recommend IP binding for keys.

Configuring Accounts & Sub-Accounts

Account Modes

OKX’s Unified Account offers three modes:

Simple: Basic trading with no margin.
Single-Currency Margin: Isolated per currency.
Multi-Currency Margin: Cross-margin with auto-borrow (configurable via web UI).

Position Modes

Net: Single-side positions (auto-adjusted).
Long/Short: Traditional dual-side positions.

Switch modes via:

POST /api/v5/account/set-position-mode

(Note: Close all positions first.)

Leverage Management

Retrieve/set leverage per instrument:

Get Leverage: GET /api/v5/account/leverage-info
Set Leverage: POST /api/v5/account/set-leverage

Example (BTC-USDT-SWAP at 3x leverage):

{  
  "lever": "3.0",  
  "mgnMode": "cross",  
  "instId": "BTC-USDT-SWAP"  
}

Trading with API v5

Order Placement

REST Example (Limit Order):

POST /api/v5/trade/order  
{  
  "instId": "BTC-USDT-SWAP",  
  "tdMode": "cross",  
  "side": "buy",  
  "ordType": "limit",  
  "px": "50912.4",  
  "sz": "1"  
}

WebSocket Order:

{  
  "id": "order_123",  
  "op": "order",  
  "args": [{  
    "instId": "BTC-USDT-SWAP",  
    "tdMode": "cross",  
    "side": "buy",  
    "px": "50912.4",  
    "sz": "1"  
  }]  
}

Monitoring Orders

Subscribe to WebSocket orders channel:

{  
  "op": "subscribe",  
  "args": [{  
    "channel": "orders",  
    "instType": "SWAP"  
  }]  
}

Updates include:

Live: Order is active.
Filled: Order executed (tradeId provided).

Batch Operations

Process up to 20 orders simultaneously:

Place: POST /api/v5/trade/batch-orders
Cancel: POST /api/v5/trade/cancel-batch-orders

Account & Positions Management

Unified Account

All instruments share one balance under the Unified Account.

WebSocket Subscriptions

Account Balance:

{  
  "op": "subscribe",  
  "args": [{  
    "channel": "account",  
    "ccy": "BTC"  
  }]  
}

Positions:

{  
  "op": "subscribe",  
  "args": [{  
    "channel": "positions",  
    "instType": "SWAP"  
  }]  
}

Max Tradable Amount

Calculate available equity + borrowable funds:

GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross

Output:

{  
  "availBuy": "213800.42",  // USDT  
  "availSell": "1.35"       // BTC  
}

FAQ

1. How do I authenticate WebSocket connections?

Send a login request with your API key, passphrase, timestamp, and signature.

2. Can I change margin modes via API?

No, margin modes (Simple/Single/Multi-currency) require web UI approval.

3. How are positions reconciled with trade IDs?

Match tradeId from order fills with positions updates. Note: Liquidations may not update tradeId.

4. What’s the rate limit for API v5?

Refer to OKX’s official documentation for current limits.

5. Is WebSocket compression enabled by default?

Yes, but ensure permessage-deflate is included in your client’s request headers.

👉 Explore advanced API features for algorithmic trading strategies.

This guide reflects API v5 as of 2025. For real-time updates, check OKX’s official documentation.