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: INLINECODE0
• API version prefix: INLINECODE1
• Demo/sandbox: same base URL, add header INLINECODE2
• 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:

CODEBLOCK0

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:

CODEBLOCK1

Authentication

Private endpoints require four request headers:

Signature formula:
CODEBLOCK2

• - timestamp: e.g. INLINECODE15
• INLINECODE16: uppercase GET or POST
• INLINECODE17: e.g. /api/v5/account/balance or INLINECODE19
• INLINECODE20: 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:

CODEBLOCK3

• - code: "0" — success
• Any other code — error; check msg for details
• INLINECODE39 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
• INLINECODE52 — cancel up to 20 orders

Place Order — Key Parameters

CODEBLOCK4

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: INLINECODE73
• Private: INLINECODE74

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
• INLINECODE79 — All public REST endpoints with params and response fields
• INLINECODE80 — All private REST endpoints, order types, instrument types
• INLINECODE81 — WebSocket URLs, subscription format, private channel auth, common channels
• INLINECODE82 — Fetch and display account balance
• INLINECODE83 — Ticker and candlestick data
• INLINECODE84 — Place a limit buy order
• INLINECODE85 — Real-time price subscription
• INLINECODE86 — Reusable auth/request helper (import in your scripts)