🔴 OKX API Overview
The OKX API is a comprehensive and well-documented API that provides programmatic access to OKX's spot, futures, options, and margin trading platforms. OKX uses a unified API structure (version 5) for all products, with a consistent authentication method across all endpoints.
OKX's API is known for its:
- Unified structure: Same endpoints for spot, futures, and options.
- Advanced features: Support for options trading, block trading, and more.
- Reliable WebSocket: Low-latency real-time data streaming.
- Comprehensive documentation: Detailed API reference with examples.
- Unified API: Single API for all products (spot, futures, options).
- Passphrase authentication: Additional security layer.
- WebSocket streams: Real-time data with low latency.
- Testnet support: Safe testing with free test funds.
🚀 Getting Started with OKX API
Before you can use the OKX API, you need to set up your credentials and understand the authentication process.
1. Get Your API Keys
-
1
Log in to your OKX account
Go to the OKX website and log in.
-
2
Navigate to API Management
Go to Account Settings → API.
-
3
Create a new API key
Click "Create API Key," enter a label, and set permissions (Read, Trade, Withdraw).
-
4
Set IP whitelist (recommended)
Add the IP address of your server for enhanced security.
-
5
Save your API key, secret, and passphrase
Copy the API key, secret, and passphrase. The secret is shown only once — store all securely.
2. Authentication
OKX API uses HMAC SHA256 signature authentication with an additional passphrase. Here's how it works:
3. Use the Testnet
Always test on the OKX testnet before deploying with real funds.
OKX Testnet: www.okx.com/testnet — Create testnet API keys and get free test funds.
📋 Key OKX API Endpoints
OKX uses a unified API structure with consistent endpoints across all product types.
| Category | Endpoint | Description | Method |
|---|---|---|---|
| Market Data | /api/v5/market/tickers |
Get ticker prices | GET |
| Market Data | /api/v5/market/candles |
Get candlestick data | GET |
| Market Data | /api/v5/market/books |
Get order book depth | GET |
| Account | /api/v5/asset/balances |
Get account balances | GET |
| Orders | /api/v5/trade/order |
Place a new order | POST |
| Orders | /api/v5/trade/cancel-order |
Cancel an order | POST |
| Orders | /api/v5/trade/orders-pending |
Get open orders | GET |
| Orders | /api/v5/trade/orders-history |
Get order history | GET |
| Orders | /api/v5/trade/fills |
Get trade history | GET |
| Futures | /api/v5/account/positions |
Get futures positions | GET |
OKX uses the same endpoints for spot, futures, and options. The instType parameter specifies the instrument type: SPOT, FUTURES, OPTIONS, or MARGIN.
🔄 OKX WebSocket Streams
OKX WebSocket streams provide real-time data for all product types.
Public WebSocket Streams
- Price Ticker:
wss://ws.okx.com:8443/ws/v5/public - Order Book:
wss://ws.okx.com:8443/ws/v5/public - Trade Stream:
wss://ws.okx.com:8443/ws/v5/public - Candlestick:
wss://ws.okx.com:8443/ws/v5/public
Private WebSocket Streams
- Account updates: Balance and position changes
- Order updates: Order status changes
- Trade updates: Trade execution
- Use multiple channels in a single connection.
- Implement auto-reconnection with exponential backoff.
- Use ping/pong keepalive messages.
- Authenticate for private streams using the login message.
🚦 OKX API Rate Limits
OKX has a rate limit of 50 requests per second per API key for most endpoints. WebSocket connections have separate limits.
| Endpoint | Rate Limit | Notes |
|---|---|---|
/api/v5/market/* |
50 req/sec | Market data endpoints |
/api/v5/trade/* |
50 req/sec | Order placement and management |
/api/v5/account/* |
50 req/sec | Account information |
/api/v5/asset/* |
50 req/sec | Asset management |
Monitor these headers in responses: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset. Always check remaining limit before sending requests.
⚠️ Common OKX API Errors
Here are the most common OKX API errors and how to fix them.
| Error Code | Message | Cause | Solution |
|---|---|---|---|
| 30001 | Invalid request | Malformed request | Check request format and parameters |
| 30008 | Insufficient balance | Not enough funds | Check balance before placing orders |
| 30009 | Invalid symbol | Symbol doesn't exist | Verify symbol is correct |
| 30010 | Invalid order size | Quantity below min or not step-sized | Check exchange filters for the symbol |
| 30011 | Invalid order price | Price below min or not tick-sized | Check exchange filters for the symbol |
| 30012 | Order not found | Order ID not found | Verify order ID before querying |
| 30013 | Order already canceled | Order already canceled | Check order status before canceling |
| 30014 | Order already filled | Order already filled | Check order status before canceling |
| 30015 | API key not found | API key doesn't exist | Verify API key is active and correct |
| 400004 | Timestamp out of sync | System time is off | Synchronize system time via NTP |
🏆 OKX API Best Practices
Follow these best practices for reliable OKX API integration.
- Always use the testnet first: Test all code on testnet before deploying with real funds.
- Secure your API keys: Use environment variables, IP whitelisting, and least privilege permissions.
- Monitor rate limit headers: Track your request count to avoid hitting limits.
- Use WebSocket for real-time data: Avoid polling REST endpoints for price updates.
- Implement error handling: Handle common errors like 30008 (insufficient balance) and 400004 (timestamp).
- Use client order IDs: Assign unique IDs to orders for better tracking.
- Stay updated: OKX API changes frequently — keep your libraries updated.
- Use the correct instrument type: Specify
instTypecorrectly for spot, futures, or options.
Use the CCXT library for a unified interface to OKX and other exchanges. It handles authentication, rate limiting, and error handling automatically.