OKX API FAQ: Common Issues and Solutions

Understanding Passphrase Security

The passphrase refers to the password you created when applying for your APIKey. This credential is critical for accessing your OKX account programmatically. Remember:

• Passphrases are irrecoverable if forgotten
• No retrieval mechanism exists - you must generate a new APIKey
• Store your passphrase securely using password managers or encrypted notes

👉 Protect your API credentials with OKX's security features

Demo Trading API Setup

To practice trading using OKX's demo environment:

1. Log in to your OKX account
2. Navigate to: Trading > Demo Trading > Personal Center
3. Select Create Demo Account APIKey
4. Begin simulated trading with virtual funds

Key benefit: Risk-free environment to test trading strategies before deploying real capital.

APIKey Expiration Policies

OKX implements smart expiration rules:

Pro Tip: Calling account balance or order placement interfaces resets the inactivity timer.

Order Placement Specifications

When placing contract orders:

• Interface defaults to contract quantity (not USDT)
• Use conversion formulas for coin-equivalent calculations
• Reference the contracts-to-coin conversion interface for accurate translations

Calculation Example:
Contracts needed = (USDT Amount) / (Contract Value × Last Price)

Calculating Price Fluctuations

Obtain market movement data through:

1. Fetch 24-hour K-line opening price (open24h)
2. Get latest transaction price (last)
3. Apply formula:
   Fluctuation Rate = [(last - open24h) / open24h] × 100%

Position Side Errors ("51000")

Resolve this by verifying your account mode:

1. Check `posMode` via interface:
   - **Hedge Mode**: Requires `posSide` (long/short)
   - **One-way Mode**: Use `net` or omit parameter
2. Cross-validate with product type:
   - Contracts mandate position sides
   - Spot trading doesn't support them

👉 Master OKX trading modes for seamless API integration

Contract Specifications Access

Retrieve critical trading parameters through:

• ctVal: Contract face value
• minSz: Minimum order quantity
  Available in the trading products information interface.

Instrument ID Format Guide

Standard instId structures:

Stop-Loss/Take-Profit Configuration

Two implementation methods:

1. Attached Orders: Use attachAlgoOrds array in main order request
2. Separate Triggers: Leverage the strategy commission interface

Price Validation Rules:

• Sell Orders: TP > Last Price > SL
• Buy Orders: TP < Last Price < SL

Timestamp Errors ("50102")

Synchronization protocol:

1. Call OKX's server time interface (UTC+8)
2. Adjust local clock to within 30 seconds of server time
3. Ensure request headers use UTC0 timestamps

Developer Note: Implement automatic time synchronization routines in your code.

Environment Mismatch ("50101")

Resolution matrix:

Account Mode Conflicts ("51010")

Mode requirements:

• Spot trading: Only in Spot Mode
• Margin/Contracts: Any non-Spot Mode
  First-time configuration must occur via web/app interface.

Lot Size Errors ("51121")

Order quantity rules:

• Must be integer multiples of minSz
• Validate against product specifications
• Round fractional quantities downward

Example: If minSz=0.01, valid quantities are 0.01, 0.02, etc.

Withdrawal Whitelisting ("58207")

API withdrawal workflow:

1. Manually add addresses via web interface
2. Enable "Non-Verified by Visa" option
3. Whitelist status overrides page settings

System Timeouts ("50004")

Peak period management:

Note: 50004 errors require result verification - the operation may have succeeded.

FAQ Section

How often should I rotate my APIKeys?

We recommend regenerating APIKeys every 90 days as part of routine security maintenance.

Can I use the same APIKey for live and demo trading?

No. Separate APIKeys are required for each environment with corresponding header parameters.

What's the maximum request rate for OKX API?

The standard limit is 20 requests per second. Prioritize request batching during high volatility.

How do I troubleshoot authentication failures?

1. Verify timestamp synchronization
2. Check APIKey environment matching
3. Validate signature generation
4. Confirm header formatting

Are there WebSocket alternatives for real-time data?

Yes. OKX provides WebSocket APIs for market data and account updates with lower latency than REST polling.

What happens to open orders when an APIKey expires?

Active orders remain operational. Only new API requests are blocked until you generate a new key.