OKX API FAQ

If you're integrating with the OKX API for trading, managing assets, or building automated strategies, understanding common technical questions and error handling is crucial. This comprehensive guide walks you through frequently asked questions about API setup, order execution, error codes, and best practices—ensuring your integration runs smoothly and efficiently.

Whether you're a developer, trader, or fintech enthusiast, this resource will help you troubleshoot issues, optimize performance, and make the most of OKX's powerful API infrastructure.

👉 Discover how to maximize your API trading potential with real-time data and secure access

Understanding Your Passphrase

When creating an APIKey, one of the most critical pieces of information is the Passphrase. This is a user-defined password set during the APIKey creation process. Unlike other credentials, OKX does not store your passphrase, meaning:

• You must remember it securely.
• If lost, it cannot be recovered.
• A new APIKey must be generated if the passphrase is forgotten.

Always store your passphrase in a secure environment such as a password manager or encrypted vault.

Creating a Demo Trading APIKey

Before risking real funds, test your strategies using OKX’s demo trading environment. To generate an APIKey for demo trading:

1. Log in to your OKX account.
2. Navigate to Trading > Demo Trading > Personal Center.
3. Select Create Demo Account APIKey.
4. Begin testing your automated strategies in a risk-free environment.

This allows developers and traders to simulate live market conditions without financial exposure.

👉 Start testing your algorithmic strategies with a free demo APIKey

Does the APIKey Expire?

APIKey expiration depends on usage and configuration:

• Non-IP-bound keys with transaction or withdrawal permissions are automatically deleted after 14 days of inactivity.
• "Inactive" means no authenticated calls (e.g., checking balances, placing orders).
• Using private endpoints like /account/balance counts as activity and prevents expiration.

However:

• Read-only APIKeys bound to specific IP addresses do not expire, even if unused.

To maintain long-term access, ensure periodic use or bind your key to a static IP.

Can Orders Be Placed in USDT or Coin Units?

No. When placing contract orders via the API, quantities are expressed in number of contracts, not in USDT or base currency units.

To convert between contract count and coin value:

• Use the contract-to-coin conversion interface.
• Refer to the ctVal field in the product information endpoint, which defines the contract’s face value in underlying assets.

Example: A BTC-USD-SWAP contract may have ctVal = 0.001, meaning each contract represents 0.001 BTC.

How to Calculate Price Fluctuation Rate

The API does not provide a direct “24h change” percentage. However, you can calculate it manually:

Fluctuation Rate = (Latest Price - 24h Open Price) / 24h Open Price × 100%

You can retrieve both values using the market data interface:

• last: latest traded price
• open24h: opening price from 24 hours ago

Use the formula: (last - open24h) / open24h

This gives you real-time price movement insights for alerts, analytics, or strategy triggers.

Resolving "51000 Parameter posSide Error"

This error occurs when the posSide parameter is incorrectly specified. The correct usage depends on your account mode:

Check Your Position Mode

Use the posMode endpoint to confirm your current setting.

Scenarios:

• Single-position mode (long/short): Required for isolated futures trading. Must specify posSide as "long" or "short".
• Net mode (buy/sell): Used in spot or leveraged trading. Only supports posSide = "net" or omitting the parameter entirely.

Ensure alignment between your trading pair type and position side to avoid rejection.

Retrieving Contract Face Value and Minimum Order Size

Use the product information interface to get essential contract details:

• Contract Face Value: Found under ctVal — indicates how much one contract is worth in the underlying asset.
• Minimum Order Quantity: Listed as minSz — defines the smallest number of contracts you can trade.

These values vary by instrument and are essential for proper order sizing and risk management.

Understanding instId Format

The instId uniquely identifies each tradable instrument. Supported formats include:

• Spot Pairs: BTC-USDT

• Perpetual Contracts:

  • BTC-USD-SWAP (coin-margined)
  • BTC-USDT-SWAP (USDT-margined)

• Futures Contracts:

  • BTC-USD-210326 (delivery date: YYMMDD)
  • BTC-USDT-210326

• Options:

  • BTC-USD-210326-2000-C (call option)
  • BTC-USD-210326-2000-P (put option)

All symbols use uppercase letters only. Use the product list endpoint to dynamically fetch valid instId values.

Setting Stop Loss and Take Profit

There are two ways to implement stop-loss and take-profit:

1. Attach to Regular Orders
   Use the attachAlgoOrds array in the place-order request. Define slTriggerPx (stop-loss) and tpTriggerPx (take-profit).
2. Standalone Algo Orders
   Use the strategy order interface to set conditional orders independently of active trades.

Both methods support trigger price types (last price, mark price, index price) for flexible risk control.

Why Do I Get Errors 51046–51049 on Trigger Prices?

These errors indicate invalid trigger price settings:

Violating these rules results in rejection. Always validate prices against current market data before submission.

Fixing "Timestamp Request Expired" (Error 50102)

This occurs when your system clock is out of sync with OKX servers by more than 30 seconds.

Solution:

• Call the /api/v5/public/time endpoint to get server time (UTC+8).
• Synchronize your local clock accordingly.
• Ensure all request headers include accurate timestamps in UTC0.

Automated systems should regularly poll server time to prevent drift.

"APIKey Does Not Match Environment" (Error 50101)

This mismatch happens when:

• Using a real account APIKey with simulated trading (x-simulated-trading: 1)
• Or vice versa

Correct Settings:

• Real trading: Use real APIKey + x-simulated-trading: 0
• Demo trading: Use demo APIKey + x-simulated-trading: 1

Double-check both credentials and headers before making requests.

"Request Unsupported Under Current Account Mode" (Error 51010)

This means your current account mode doesn't support the requested operation.

For margin or contract trading:

• You must switch from spot-only mode to one of the following:

  • Single-currency margin
  • Multi-currency margin
  • Portfolio margin

Change this via:

• Web/App: Trading page → Settings → Account mode
• API: Only after initial setup via UI

Note: First-time changes must be done through the front-end interface.

"Order Quantity Must Be Multiple of Lot Size" (Error 51121)

Each contract has a minimum trade unit (minSz) and lot size increment. Your order quantity must be a multiple of this value.

Example:

• If minSz = 1 and lot size = 1 → valid orders: 1, 2, 3...
• If lot size = 5 → valid orders: 5, 10, 15...

Fetch these details via the product information endpoint to avoid formatting errors.

Withdrawal Error: "Address Not Whitelisted for Verification Exemption" (58207)

Even if allowlist verification is disabled on the withdrawal page, API withdrawals require explicit whitelisting:

Steps:

1. Add the withdrawal address in your OKX account.
2. Enable "Non-verified address" for API use.
3. Confirm the address appears in your withdrawal allowlist.

Disabling verification on the page does not override API security policies.

"API Endpoint Request Timeout" (Error 50004)

This indicates temporary server overload. Common causes:

• High traffic at fee collection times: 8 AM, 4 PM, 12 AM UTC
• Network congestion or retry storms

Best Practices:

• Avoid placing critical orders during peak hours.
• Implement exponential backoff for retries.
• Always verify order status after timeout — the request may have succeeded silently.

Use /trade/order history queries to confirm execution state.

👉 Access reliable, low-latency API endpoints for seamless trading experiences

Frequently Asked Questions (FAQ)

Q: Can I recover a lost passphrase?

A: No. The passphrase is encrypted and not stored by OKX. If lost, you must create a new APIKey.

Q: How often should I rotate my APIKey?

A: For security, rotate keys every 3–6 months or immediately after suspected exposure.

Q: Is IP binding required?

A: Not required, but highly recommended to prevent unauthorized access.

Q: Can I use the same APIKey for real and demo trading?

A: No. Real and simulated environments require separate keys with distinct headers.

Q: What permissions do I need for algo orders?

A: Ensure your APIKey has trading permission enabled and includes access to strategy interfaces.

Q: How fast are API responses typically?

A: Under normal load, most responses are under 100ms. Latency increases during market volatility or system peaks.

By mastering these core concepts and error resolutions, you can build robust, efficient integrations with the OKX API—whether for personal trading bots or enterprise-level applications.