OKX API v5 Skill

Overview

OKX API v5 provides REST and WebSocket interfaces for spot trading, derivatives (perpetual swaps, futures, options), market data, and account management.

• Base URL: https://www.okx.com
• API version prefix: /api/v5/
• Demo/sandbox: same base URL, add header x-simulated-trading: 1
• Auth: HMAC SHA256 signature (private endpoints only)
• Rate limits: public endpoints by IP; private endpoints by User ID

All examples use scripts/okx_auth.py — a reusable helper that handles credential loading, signing, and response parsing.

Configuration Setup

Store credentials in ~/.openclaw/openclaw.json under the top-level env field. OpenClaw automatically injects these into the agent environment:

{
  "env": {
    "OKX_API_KEY": "your-api-key",
    "OKX_SECRET_KEY": "your-secret-key",
    "OKX_PASSPHRASE": "your-passphrase",
    "OKX_DEMO": "1"
  }
}

Set OKX_DEMO=1 to use sandbox mode (paper trading). Remove or set to 0 for live trading.

You can also export these in your shell:

export OKX_API_KEY="your-api-key"
export OKX_SECRET_KEY="your-secret-key"
export OKX_PASSPHRASE="your-passphrase"
export OKX_DEMO="1"

Authentication

Private endpoints require four request headers:

Signature formula:

pre_sign = timestamp + METHOD + path_with_query + body
signature = base64(hmac_sha256(pre_sign, secret_key))

• timestamp: e.g. 2024-01-15T10:30:00.123Z
• METHOD: uppercase GET or POST
• path_with_query: e.g. /api/v5/account/balance or /api/v5/market/ticker?instId=BTC-USDT
• body: JSON string for POST, empty string "" for GET

Use scripts/okx_auth.py — it handles all of this automatically. See references/authentication.md for edge cases and error codes.

Common Operations Quick Reference

Response Handling

All REST responses follow this envelope:

{
  "code": "0",
  "msg": "",
  "data": [...]
}

• code: "0" — success
• Any other code — error; check msg for details
• data is always an array (even for single objects)

Common error codes:

The make_request() function in scripts/okx_auth.py raises a RuntimeError when code != "0", so you can catch errors cleanly.

Rate Limits

OKX enforces rate limits per endpoint group:

If you hit 50011, sleep 2 seconds and retry. For bulk operations, use batch endpoints:

• POST /api/v5/trade/batch-orders — place up to 20 orders
• POST /api/v5/trade/cancel-batch-orders — cancel up to 20 orders

Place Order — Key Parameters

{
  "instId": "BTC-USDT",
  "tdMode": "cash",
  "side": "buy",
  "ordType": "limit",
  "px": "42000",
  "sz": "0.001"
}

See examples/place-order.py for a complete working example.

WebSocket

For real-time data (prices, order updates, position changes), use WebSocket instead of polling REST.

• Public: wss://ws.okx.com:8443/ws/v5/public
• Private: wss://ws.okx.com:8443/ws/v5/private

Subscribe to channels by sending JSON messages. Private channels require a login operation first using the same HMAC signature scheme.

See references/websocket.md and examples/websocket-ticker.py.

References

• references/authentication.md — Signature details, edge cases, auth error troubleshooting
• references/market-data-endpoints.md — All public REST endpoints with params and response fields
• references/trading-endpoints.md — All private REST endpoints, order types, instrument types
• references/websocket.md — WebSocket URLs, subscription format, private channel auth, common channels
• examples/get-balance.py — Fetch and display account balance
• examples/get-market-data.py — Ticker and candlestick data
• examples/place-order.py — Place a limit buy order
• examples/websocket-ticker.py — Real-time price subscription
• scripts/okx_auth.py — Reusable auth/request helper (import in your scripts)