OKX API Frequently Asked Questions (FAQ)

·

What is a Passphrase?

A passphrase is the password you entered when registering your API Key. You must remember this information yourself. If you forget it, you cannot retrieve it and will need to create a new API Key.

How to Create a Demo Trading API Key?

To trade using the demo API, you need to create an API Key specifically for the demo environment. Simply follow these steps:

  1. Log in to your OKX account.
  2. Navigate to 'Trade' > 'Demo Trading'.
  3. Go to the 'Personal Center'.
  4. Select 'Create Demo Account API Key'.
  5. Start demo trading.

Does an API Key Expire?

API Keys that are not bound to an IP and have trading or withdrawal permissions will be automatically deleted after 14 days of inactivity. An API Key is not considered inactive if it is used to call a private interface or an interface related to account identity verification, such as checking account balances, invoice data, or placing orders.

Only read-only API Keys that are IP-bound or have specific permissions will not expire.

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

No. For contract orders, the interface defaults to ordering by contract quantity. If you need to calculate the conversion between contract quantity and coin amount, you can reference the specific conversion interface.

How to Get the Price Change Rate via the API?

The API cannot directly fetch the price increase or decrease percentage, but you can calculate it using this formula:

(Latest Trade Price - 24-hour Candle Open Price) / 24-hour Candle Open Price * 100%

You can obtain the necessary data for this formula through the market data interface.

Why Am I Getting Error "51000 Parameter posSide error"?

First, you need to check your account mode (buy/sell mode or open/close mode). You can retrieve your posMode via the appropriate endpoint.

Important Notes:

Which Interface Provides Contract Denomination and Minimum Order Quantity?

You can use the instruments interface to fetch basic information on trading products.

Look for the ctVal field for contract denomination and the minSz field for the minimum order size.

What is the Format of instId?

You can directly use the instruments interface to get the basic information for trading products.

Examples of instId format:

How to Set a Stop-Loss and Take-Profit Order?

If you want to attach a take-profit or stop-loss to a primary order, you can reference the place order interface and use the attachAlgoOrds parameter array.

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

Why Errors 51046, 51047, 51048, 51049 When Setting Trigger Prices?

These errors relate to the rules for setting trigger prices for stop-loss and take-profit orders:

What is "API Error: 50102 Request timestamp expired"?

This error occurs when the timestamp in your request has expired. You need to call the system time interface to synchronize your local time with the exchange's server time. Keeping the time difference within 30 seconds can help avoid this issue.

Note: The timestamp in the request header must be in UTC±0. However, the time returned by the server time interface is in UTC+8.

What is "API Error: 50101 APIKey does not match the current environment"?

This error is caused by a mismatch between the API Key and the environment you are calling. A real account API call requires using a real account API Key and setting the x-simulated-trading header value to 0. A demo account API call requires using a demo account API Key and setting the x-simulated-trading header value to 1.

What is "API Error: 51010 Request not supported in current account mode"?

This error is related to your account mode. To trade contracts or isolated margin, you need to switch your account mode to one of the three specific modes, excluding the simple spot mode. You can configure this via the API mode setting endpoint or directly on the OKX website or mobile app.

Note: The initial mode must be set on the web platform or mobile app. Look for 'Account Mode' in the main trading menu settings.

What is "API Error: 51121 Order quantity must be a multiple of the lot size"?

In the API, contract orders are typically placed in lots and must be a multiple of the minimum order size (minSz) for that instrument. You can get the minSz value from the instruments endpoint.

Why Withdrawal Error 58207 and Allowlist Verification Issues?

To withdraw coins via the API, you must first add the withdrawal address to your allowlist on the OKX website and verify it (the "unverified by visa" check). If the allowlist verification toggle is turned off on the website, it will not affect the API's withdrawal functionality; the API will still only process withdrawals to addresses on your list.

What is "API Error: 50004 API endpoint request timeout"?

Error 50004 usually indicates excessive server load. The daily funding fee settlement times (often around 08:00, 16:00, and 24:00 UTC) are periods of high server pressure. It's advisable to stagger trading activity around these times. If you encounter 50004 at other times, simply retry your request later.

Critical Note: If an order is placed and you receive a 50004 error, the actual outcome of the API request is indeterminate—it may have succeeded or failed. You must check the actual order state or account balance to confirm the result and avoid duplicate orders.

👉 Explore advanced API trading strategies

Frequently Asked Questions

What is the most common mistake when starting with the OKX API?
The most common error is incorrect timestamp synchronization, leading to error 50102. Always ensure your system clock is synced with OKX server time using their provided endpoint.

How often should I rotate my API Keys for security?
For optimal security, it's a good practice to review and potentially rotate your API Keys every 3-6 months, especially those with trading or withdrawal permissions. Always use IP whitelisting for added security.

Can I use the same API Key for both real and demo trading?
No, you cannot. The real and demo trading environments are completely separate. You must create and use distinct API Keys for each environment and ensure the x-simulated-trading header is set correctly (0 for real, 1 for demo).

What is the rate limit for the OKX API?
Rate limits vary depending on the specific API endpoint and your user level. Generally, public endpoints have a higher rate limit than private ones. You can find your current rate limits specified in the response headers of your API requests.

Why is my order not being executed immediately?
This could be due to several factors: the order type (e.g., a limit order vs. a market order), market volatility causing price shifts, or the order size being too large for the current market depth. Check the order parameters and current market conditions.

Where can I find comprehensive documentation for all API endpoints?
The complete and most up-to-date documentation for the OKX API is available directly on their official website. It details every endpoint, parameter, and possible response code.