OKX V5 API Reference Documentation

Authentication

Signature Generation (HMAC SHA256 + Base64)

The signature algorithm:

signature = Base64(HMAC_SHA256(secret_key, timestamp + method + request_path + body))

Java Example:
```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public static String sign(String timestamp, String method,
String requestPath, String body, String secretKey) {
try {
String preHash = timestamp + method + requestPath + body;
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
mac.init(spec);
return Base64.getEncoder().encodeToString(mac.doFinal(preHash.getBytes()));
} catch (Exception e) {
throw new RuntimeException("Signature failed", e);
}
}
```

Python Example:
```python
import hmac, base64, hashlib

def sign(timestamp, method, request_path, body, secret_key):
pre_hash = timestamp + method + request_path + body
signature = hmac.new(
secret_key.encode(), pre_hash.encode(), hashlib.sha256
).digest()
return base64.b64encode(signature).decode()
```

Go Example:
```go
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
)

func sign(timestamp, method, requestPath, body, secretKey string) string {
preHash := timestamp + method + requestPath + body
mac := hmac.New(sha256.New, []byte(secretKey))
mac.Write([]byte(preHash))
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}
```

Required Headers

All authenticated REST requests MUST include:

Market Types

WebSocket

Public Channel

wss://ws.okx.com:8443/ws/v5/public

Access market data without authentication: tickers, order books, trades, mark prices, funding rates, etc.

Private Channel

wss://ws.okx.com:8443/ws/v5/private

Requires authentication (login). Access account data, order updates, position changes, balance updates.

Business Channel

wss://ws.okx.com:8443/ws/v5/business

Requires authentication. Access business-specific channels (requires application).

Ping/Pong

• Client must send a ping message if no message has been sent in the last 30 seconds
• Server responds with pong
• If no pong received, client should reconnect

{"op": "ping"}

{"op": "pong"}

Subscription Example

{
    "op": "subscribe",
    "args": [
        {
            "channel": "tickers",
            "instId": "BTC-USDT"
        }
    ]
}

Login (Private Channel)

{
    "op": "login",
    "args": [
        {
            "apiKey": "YOUR_API_KEY",
            "passphrase": "YOUR_PASSPHRASE",
            "timestamp": "2023-01-01T00:00:00.000Z",
            "sign": "BASE64_SIGNATURE"
        }
    ]
}

WebSocket login signature: timestamp + "GET" + "/users/self/verify" (no body).

Common REST Endpoints

Account

Trade

Market Data

Order Placement Example

REST - Place Limit Order

POST /api/v5/trade/order

Request Body:
json { "instId": "BTC-USDT-SWAP", "tdMode": "cross", "side": "buy", "ordType": "limit", "sz": "1", "px": "20000" }

Response:
json { "code": "0", "msg": "", "data": [ { "clOrdId": "", "ordId": "123456", "tag": "", "sCode": "0", "sMsg": "" } ] }

Rate Limits

• REST: 20 requests / 2 seconds per endpoint (varies by endpoint)
• WebSocket: 1 subscription request / second
• Public WebSocket data: throttled per channel
• Always implement exponential backoff on 429 responses

Error Codes

Best Practices

1. Timestamp synchronization: Ensure server time is synced via NTP; timestamp must be within 30 seconds of OKX server time
2. Exponential backoff: On rate limit (429) or 5xx errors, implement exponential backoff starting at 1s
3. WebSocket reconnection: Automatically reconnect on disconnect with backoff; resubscribe all channels
4. Demo first: Always test on demo trading (x-simulated-trading: 1) before live
5. Idempotency: Use clOrdId to prevent duplicate orders
6. Error logging: Log full error responses including code, msg, and data fields
7. Connection pooling: Reuse HTTP connections for REST calls
8. WebSocket heartbeat: Maintain 30-second ping/pong cycle