How to use the API for automated trading on OKX

The OKX API enables automated trading via REST and WebSocket interfaces, allowing order placement, real-time data streaming, and account management with secure HMAC authentication.

Aug 07, 2025 at 05:21 pm

Understanding the OKX API for Automated Trading

The OKX API provides a powerful interface for users to automate their trading strategies, access real-time market data, and manage their accounts programmatically. Before initiating any automated trading, it's essential to understand the types of APIs offered by OKX. The platform supports REST API, WebSocket API, and Web3.js API, with the first two being most relevant for automated trading. The REST API allows you to place orders, check balances, and retrieve historical data using HTTP requests. The WebSocket API enables real-time streaming of market data, order updates, and account changes with low latency.

To get started, you must generate an API key from your OKX account. Navigate to the API Management section under your account settings. Here, you will create a new API key by specifying a name, passphrase, and binding IP addresses for security. It is critical to restrict access to specific IPs to prevent unauthorized usage. The generated key consists of three components: API Key, Secret Key, and Passphrase. These must be stored securely, as they grant full access to your trading account.

Setting Up Your Development Environment

To use the OKX API effectively, you need a proper development environment. Most developers use Python due to its simplicity and rich ecosystem of libraries. Install Python (preferably version 3.8 or higher) and set up a virtual environment to manage dependencies. Use pip to install required packages such as requests for HTTP communication and websockets for handling WebSocket connections.

pip install requests websockets

Next, create a configuration file (e.g., config.py) to store your API credentials securely. Never hardcode your keys in your main script. Your configuration should include:

• API Key
• Secret Key
• Passphrase
• Base URL (e.g., https://www.okx.com for REST)

Ensure this file is added to .gitignore if you're using version control. This prevents accidental exposure of sensitive data.

Authenticating Requests with OKX API

OKX uses HMAC-SHA256 encryption for request authentication. Every private API request must include headers with specific fields: OK-ACCESS-KEY, OK-ACCESS-SIGN, OK-ACCESS-TIMESTAMP, and OK-ACCESS-PASSPHRASE. The signature is generated by concatenating the timestamp, HTTP method, endpoint path, and request body (if any), then signing it with your Secret Key.

Here’s how to generate the signature in Python:

import hmac
import hashlib
import json
def generate_signature(timestamp, method, url, body, secret_key):
message = timestamp + method + url + (json.dumps(body) if body else "")
mac = hmac.new(bytes(secret_key, 'utf-8'), bytes(message, 'utf-8'), hashlib.sha256)
return mac.hexdigest()
Include this function in your API wrapper. The timestamp must be in ISO format (e.g., 2024-04-05T12:00:00.000Z). Always verify the system clock is synchronized with UTC to avoid authentication errors.
Placing Orders via REST API
To execute trades automatically, use the Place Order endpoint. The endpoint URL is /api/v5/trade/order. You must send a POST request with a JSON body containing the required parameters:
instId: Instrument ID (e.g., BTC-USDT-SWAP)
tdMode: Trade mode (cash, isolated, or cross)
ordType: Order type (limit, market, post_only, etc.)
sz: Order size
px: Price (required for limit orders)
Example request body:
{
"instId": "BTC-USDT-SWAP",
 "tdMode": "cross",
 "ordType": "limit",
 "sz": "0.001",
 "px": "60000"
}

Use the requests library to send the request:

import requests
from config import API_KEY, SECRET_KEY, PASSPHRASE
url = "https://www.okx.com/api/v5/trade/order"
headers = {
"OK-ACCESS-KEY": API_KEY,
"OK-ACCESS-PASSPHRASE": PASSPHRASE,
"Content-Type": "application/json"
}
body = {
"instId": "BTC-USDT-SWAP",
"tdMode": "cross",
"ordType": "limit",
"sz": "0.001",
"px": "60000"
}
timestamp = "2024-04-05T12:00:00.000Z"
signature = generate_signature(timestamp, "POST", "/api/v5/trade/order", body, SECRET_KEY)
headers["OK-ACCESS-SIGN"] = signature
headers["OK-ACCESS-TIMESTAMP"] = timestamp
response = requests.post(url, headers=headers, json=body)
print(response.json())

Check the response for code and msg. A code of 0 indicates success.

Streaming Market Data with WebSocket

For real-time trading decisions, connect to OKX’s WebSocket API. This allows you to receive live updates on order books, trades, and your order status. Use the websockets library to establish a connection to wss://ws.okx.com:8443/ws/v5/public for public channels or wss://ws.okx.com:8443/ws/v5/private for private data.

Subscribe to the ticker or depth channel to monitor price changes:

import asyncio
import websockets
import json
async def listen_to_ticker():
uri = "wss://ws.okx.com:8443/ws/v5/public"
async with websockets.connect(uri) as websocket:
    subscribe_message = {
        "op": "subscribe",
        "args": [
            {
                "channel": "tickers",
                "instId": "BTC-USDT"
            }
        ]
    }
    await websocket.send(json.dumps(subscribe_message))

    while True:
        response = await websocket.recv()
        data = json.loads(response)
        if "data" in data:
            print("Latest price:", data["data"][0]["last"])
Run this coroutine to continuously receive updates. Handle disconnections and implement reconnection logic for robustness.
Managing Risk and Monitoring Orders
Automated trading requires constant monitoring. Use the Get Order Details endpoint (/api/v5/trade/order) to check the status of a specific order by ordId. Cancel orders using the Cancel Order endpoint (/api/v5/trade/cancel-order) if market conditions change.
Implement logging to record all actions:
import logging
logging.basicConfig(filename='trading.log', level=logging.INFO)
logging.info(f"Order placed: {response.json()}")

Set up alerts for failed requests or unexpected price movements. Use circuit breakers to halt trading if losses exceed a threshold.

Frequently Asked Questions

Can I use the OKX API without enabling two-factor authentication (2FA)?

No. For security reasons, OKX requires 2FA to be enabled on your account before you can create API keys. This adds an extra layer of protection against unauthorized access.

What rate limits apply to the OKX API?

OKX enforces rate limits based on the type of request. Public endpoints allow up to 20 requests per 2 seconds per IP. Private endpoints are limited to 6 requests per 2 seconds per API key. Exceeding these limits results in a 429 error.

Is testnet available for OKX API development?

Yes. OKX provides a demo trading environment accessible via a different base URL: https://www.okx.com. You can simulate trades without risking real funds. Switch the base URL in your configuration and use demo-specific API keys.

How do I handle API downtime or connection loss?

Implement retry logic with exponential backoff. For WebSocket connections, listen for close events and attempt reconnection after a delay. Store order states locally to recover from interruptions.