OKX API Common Questions Answered (OKX Referral Code: SUPER20OFF)

If you're building trading bots, connecting third-party tools, or just trying to automate your crypto operations on OKX, you've probably hit a few confusing error messages. Maybe your API key suddenly stopped working, or you're scratching your head over why your order won't go through. This guide walks through the most common API headaches developers face on OKX—from passphrase mysteries to timestamp errors—and shows you exactly how to fix them. By the end, you'll know how to set up demo trading, handle contract orders, and troubleshoot those cryptic error codes that pop up at 3 AM.

What's a Passphrase Anyway?

Think of your passphrase as the secret handshake you created when setting up your API key. You typed it in once during setup, and OKX expects you to remember it forever. There's no "forgot password" link here—if it slips your mind, you're starting over with a fresh API key. So yeah, write it down somewhere safe.

Setting Up Demo Trading

Want to test your trading bot without risking real money? Smart move. Here's how you spin up a demo API key:

Log in to OKX → Trading → Demo Trading → Personal Center → Create Demo Account APIKey → Start Demo Trading

The demo environment runs on separate API keys from your live account, so don't mix them up. Testing strategies in the sandbox first can save you from expensive mistakes when you go live.

When Do API Keys Expire?

Here's something that catches people off guard: if your API key has trading or withdrawal permissions and isn't bound to a specific IP address, OKX will auto-delete it after 14 days of sitting idle. But "idle" doesn't mean what you might think—calling any private endpoint (like checking your balance or placing orders) counts as activity.

Read-only keys bound to an IP? Those stick around indefinitely.

Can You Place Orders in Currency Units?

Nope. Contract orders go through in "number of contracts," not dollar amounts or coin quantities. If you need to convert between contracts and actual cryptocurrency amounts, OKX has a unit conversion endpoint that does the math for you.

Calculating Price Changes

The API won't hand you a nice percentage like "+5.3%" directly, but you can calculate it yourself:

(Latest price - Opening price from 24h ago) / Opening price from 24h ago × 100%

Grab both values from the ticker endpoint and run the calculation on your end.

The "51000 Parameter posSide Error" Mystery

This error means your position side parameter doesn't match your account mode. First, check whether you're in "buy/sell mode" or "long/short mode" by calling the account configuration endpoint and looking at posMode.

The rules:

• Long/short mode + contracts: You must include posSide and set it to either long or short

• Buy/sell mode (or spot/leverage trading in long/short mode): Use posSide: net or just leave it out

Finding Contract Face Value and Minimum Order Size

Need to know the contract specifications? The instruments endpoint gives you everything:

• ctVal: Contract face value

• minSz: Minimum order quantity

The instId format you'll need is also available in that same endpoint, so you can see exactly how to structure your trading pair identifiers.

👉 Start trading smarter with OKX's powerful API features—get 20% off fees forever

Setting up proper API access is just the beginning. With the right configuration and OKX's comprehensive toolset, you can automate sophisticated trading strategies that would be impossible to execute manually.

Setting Stop Loss and Take Profit

There are two ways to handle this:

Attached orders: When placing your main order, include stop-loss and take-profit parameters in the attachAlgoOrds array of the place order endpoint.

Separate algo orders: Use the algo order endpoint to create standalone stop-loss or take-profit orders.

Why Are Trigger Prices Getting Rejected? (Errors 51046-51049)

The trigger price rules trip people up constantly. Here's the logic:

When selling (or closing long positions):

• Take-profit trigger > current market price

• Stop-loss trigger < current market price

When buying (or closing short positions):

• Take-profit trigger < current market price

• Stop-loss trigger > current market price

Think about it: you take profit when the price moves in your favor, and stop losses kick in when it moves against you.

"50102 Timestamp Request Expired" Error

Your local clock is out of sync with OKX's servers. Call the system time endpoint to grab the correct time, then adjust your requests. Keep the time difference under 30 seconds.

Important quirk: The timestamp in your request header uses UTC+0, but the server time endpoint returns UTC+8. Don't forget to convert.

"50101 APIKey Doesn't Match Current Environment"

You're mixing live and demo environments. Real trading requires:

• Real account API key

• x-simulated-trading: 0 in headers

Demo trading requires:

• Demo account API key

• x-simulated-trading: 1 in headers

"51010 Request Unsupported Under Current Account Mode"

Some operations require specific account modes. For leverage or contract trading, you need to switch out of spot-only mode. Change this via the position mode endpoint or in the web/app settings under Trading → Settings → Account Mode.

First-time setup note: The initial account mode change must be done through the web or app interface, not the API.

"51121 Order Quantity Must Be a Multiple of Lot Size"

Contract orders must be whole multiples of the minimum order size for that trading pair. Check the minSz field from the instruments endpoint to see what you're working with.

"58207 Withdrawal Address Not Whitelisted"

API withdrawals require you to add the destination address on the website first and check the "exempt from verification" box. The whitelist toggle on the withdrawal page doesn't affect API behavior—you still need to explicitly exempt addresses for API use.

"50004 API Endpoint Request Timeout"

This timeout doesn't tell you whether your request succeeded or failed—you need to check separately. It usually happens when servers are slammed, especially at 8 AM, 4 PM, and midnight UTC (funding rate collection times).

If you get a 50004 on an order placement, don't assume anything. Check your order status through the appropriate endpoint to see what actually happened.

"50119 API Key Doesn't Exist"

This typically means you're using the wrong regional domain for your account. Make sure your API calls match where your account is actually registered.

"50110" Error When Connecting Third-Party Software

Third-party trading tools can be picky about API key types. Try creating a new API key with:

• Transaction permissions enabled

• No IP binding

• Then reconnect your software

Wrapping Up

Working with OKX's API doesn't have to be a constant battle with error messages. Most issues come down to a handful of common mistakes: mismatched account modes, expired timestamps, mixing up demo and live credentials, or forgetting how position sides work. Once you understand the patterns behind these errors, troubleshooting becomes straightforward. Whether you're building automated strategies or just trying to integrate with your favorite trading tools, OKX provides the flexibility and power to make it happen—especially when you're getting 20% off trading fees with SUPER20OFF. Keep this guide bookmarked for when those midnight coding sessions inevitably hit a snag.