OKX API Frequently Asked Questions

·

What is the Passphrase?

The passphrase refers to the password you entered when initially requesting your API Key. It is crucial to remember this passphrase, as it cannot be recovered if forgotten. In such cases, you will need to create a new API Key entirely.

How to Create a Demo Account API Key

To engage in trading via the demo account API, you must first create a dedicated API Key for the demo environment. Follow these steps:

  1. Log in to your OKX account.
  2. Navigate to the 'Trading' section.
  3. Select 'Demo Trading'.
  4. Go to the 'Personal Center'.
  5. Choose 'Create Demo Account APIKey'.
  6. You can then 'Start Demo Trading'.

Does the API Key Expire?

API Keys that are not bound to a specific IP address and have transaction or withdrawal permissions will be automatically deleted after 14 days of inactivity. Importantly, an API Key is not considered inactive if it is used to call private interfaces or account-related endpoints that require identity verification, such as checking account balances, viewing billing data, or placing orders.

API Keys that are read-only and associated with a specific IP address or have specific permissions will not expire.

Can I Place Orders in USDT or Currency Units via the API Interface?

No. For contract orders, the API interface requires orders to be placed using the number of contracts. If you need to convert between the number of contracts and the cryptocurrency amount, you can utilize the dedicated contract-to-currency conversion interface.

How to Obtain the Price Fluctuation Rate via the API

The API does not provide a direct endpoint to fetch the price increase or decrease percentage. However, you can calculate it using this formula:

(last - open24h) / open24h * 100%

Where:

The data required for this calculation can be obtained through the market data interface.

Error Message: "51000 Parameter posSide error"

This error typically relates to your account's position mode. First, you must check your account's mode (net mode, long/short mode, etc.), which can be retrieved via the relevant endpoint to obtain the posMode parameter.

Note:

Which Interface Provides Contract Face Value and Minimum Order Quantity?

You can use the instruments interface to obtain basic information on trading products. This endpoint provides details such as contract face value (ctVal) and the minimum order quantity (minSz).

What is the Format of instId?

The format for the instrument ID (instId) can be retrieved directly using the instruments interface. Here are some common examples:

How to Set Stop-Loss and Take-Profit Orders

If you wish to attach a take-profit or stop-loss order to a primary order, you can reference the placement order interface and use the attachAlgoOrds array parameters.

However, if you want to place a standalone stop-loss or take-profit order, you should use the strategy order placement interface.

Why Do I Get Errors 51046, 47, 51048, 49 When Setting Trigger Prices?

These errors occur due to rules governing trigger price settings for take-profit and stop-loss orders:

Error: "50102 Timestamp request expired"

This error indicates that the timestamp in your API request has expired. You must synchronize your local time with the server's time by calling the system time interface. Keeping the time difference within 30 seconds will help prevent this issue.

Note: The timestamp in the request header must be in UTC0. When you call the server time interface, the returned time is displayed in UTC+8.

Error: "50101 APIKey does not match the current environment"

This error arises from a mismatch between the API Key used and the trading environment (real vs. demo).

Error: "51010 Request unsupported under current account mode"

This error is related to your account's trading mode. To trade on leverage or in the unified account mode, you must set your account to the appropriate mode (e.g., cross, isolated, multi-currency margin), excluding the simple spot mode. You can configure this via the set account mode interface, or directly on the OKX website or mobile app.

Note: The initial mode setting must be configured on the web platform or mobile app. You can find this option under the main trading page menu - 'Account Mode'.

Error: "51121 Order quantity must be a multiple of the lot size"

For contract orders via the API, the order quantity must be in units of contracts (lots) and must be an integer multiple of the minimum order quantity (lot size) for that instrument. You can obtain the minimum order quantity from the minSz field provided by the instruments interface.

Withdrawal Error: "58207 Withdrawal address is not whitelisted for verification exemption"

To withdraw funds using the API, you must first add the withdrawal address to your whitelist on the OKX website/app and select the 'No verification needed for this address' option. The fact that the whitelist verification toggle is turned off on the withdrawal page does not affect the API's functionality; the address still needs to be pre-whitelisted with the correct permissions.

Error: "50004 API endpoint request timeout"

Error 50004 usually indicates high server load. Peak server pressure often occurs around daily capital fee collection times (e.g., 8, 16, and 24 hours UTC). It is advisable to avoid making transactions during these periods. If you encounter a 50004 error at other times, simply retry your request later. 👉 Explore more strategies for handling API timeouts

Critical Note: An order placement request that returns a 50004 error does not confirm the actual result of the operation. The request may have succeeded or failed. You must check the actual order status or trade history using the relevant endpoints to confirm the outcome.

Frequently Asked Questions

What is the main difference between real and demo API Keys?
Real API Keys are for live trading with actual funds, while demo API Keys are for practicing and testing strategies in a simulated market environment with virtual funds. They cannot be used interchangeably.

How often should I synchronize my server's time with OKX?
It is recommended to synchronize your server time with OKX's server time at least once a day, or more frequently if your system clock is prone to drift, to avoid timestamp expiration errors.

Can I use the same API Key for multiple trading algorithms?
Yes, you can use one API Key for multiple algorithms. However, for better security and rate limit management, it is often advisable to create separate API Keys for different applications or strategies.

What does 'inactivity' mean for API Key expiration?
Inactivity is defined as not making any successful calls to private API endpoints that require authentication for a continuous 14-day period. Checking your account balance or order history counts as activity.

Where can I find a complete list of API error codes?
A comprehensive list of error codes, their meanings, and potential solutions is available in the official OKX API documentation. 👉 View real-time tools and documentation

Is there a rate limit for API requests?
Yes, OKX enforces rate limits on API requests. The specific limits depend on your account tier and the type of endpoint being called. Exceeding these limits will result in rate limit errors.