OKX API Guide: Create a Key, Set Permissions, Auto Trade

From creating an API key, choosing permissions and setting an IP whitelist, to what each error code means when an order is rejected and how to handle it.

Last updated 2026-11
Disclosure: the OKX sign-up links in this article are Blave partner links. If you sign up through them, Blave may receive a commission.

No OKX account yet? Sign up for OKX

Key Takeaways
  • An OKX API key has three parts: API key, secret key and passphrase. You set the passphrase yourself, and if you forget it you have to delete the key and make a new one.
  • Auto trading needs only Read and Trade. Never enable Withdraw.
  • OKX automatically deletes a key that has trade permission and no IP bound after 14 days of inactivity.
  • A 50004 or 51149 timeout on an order doesn't mean it didn't fill. Check the order first and never just resend it.

What is the OKX API?

The OKX API lets a program talk to your OKX account directly: check balances, check positions, place and cancel orders, all without opening the website. Auto trading programs place orders by rules through the API.

To use the API, first create a key. The program uses it to prove it's authorized by your account. What the key can do depends on the permissions you enable when you create it.

How do you create an OKX API key?

Sign Up for OKX
Never enable withdrawal. Auto trading only needs read and trade. Even if the key leaks, nobody can move your coins without withdrawal permission.
  1. Log in to OKX on the web, open Profile → API and connections and click Create API key.
  2. Enter a name for the API key and choose the account and purpose.
  3. Set an IP whitelist (see the next section).
  4. Tick Read and Trade. Leave Withdraw unticked.
  5. Set a passphrase and write it down. OKX won't show it again after the key is created.
  6. Finish the security check, then copy the API key and secret key and keep them somewhere safe.

Give all three to your auto trading program. Miss one and it can't connect.

Should you set an IP whitelist?

The OKX API FAQ states that a key with trade or withdrawal permission and no IP bound is deleted after 14 days of inactivity. With an IP bound, the key doesn't expire from inactivity, and anyone who gets the key can't use it from anywhere else. One key can bind up to 20 IPs.

If you bind one, enter the public IP of the machine running the program, not your phone's or the one you browse from. A home connection's IP can change, and when it does, add the new IP to the whitelist.

With Blave Agent, the connect dialog on a cloud machine shows the machine's IP, so just enter that. The desktop app doesn't require binding, but if you don't, remember the 14-day rule.

Common OKX API error codes

These are the errors auto trading runs into most. The meanings follow the official OKX API docs (51008 follows how Blave's order code classifies it), and the fixes are general advice.

CodeMeaningWhat to do
First group: key and permission problems, rejected as soon as you connect or place an order
50111Invalid API keyCheck it was pasted correctly with no extra spaces at either end
50113Invalid signatureUsually a wrong secret key. Paste it again
50105Wrong passphraseEnter the one you set when creating the key, not your login password
50110IP not on the whitelistAdd the new IP of the machine running the program to the whitelist
50119Key doesn't existIt may have been deleted (for example by the 14-day rule). Create a new one
50100API frozenContact OKX support
Second group: the key is fine, but this order can't go through
51010Not supported in the current account modeSpot mode can't trade futures. Switch to a mode that supports futures in the account mode setting
51008Insufficient marginAdd funds or lower the strategy amount
51020Below the minimum order sizeRaise the strategy amount, or pick a coin with a smaller minimum unit
50102Request timestamp expiredThe clock on the machine running the program is off. Turn on automatic time sync
Third group: the result is uncertain, so be most careful
50004API request timed outDon't resend. Check the order first
51149Order timed outDon't resend. Check the order first
50001Service temporarily unavailableDon't resend. Check the order first
50026System errorDon't resend. Check the order first

The OKX docs state that 50004 and 51149 "does not mean that the request was successful or failed". The order may already have filled, and resending it would place it twice. Blave Agent never resends the same order on any of these four codes. For a futures market order it checks whether the order filled before deciding what to do next. Any other order stops and reports back, with no automatic retry.

If you write your own code against the OKX API, this is where things go wrong most often.

Connect OKX through Blave Agent and skip all this

Blave Agent's order code already handles everything above, including syncing time with OKX on 50102 and never resending after a timeout. Paste the API key, secret key and passphrase into Auto Trading › Connect Account › OKX, and the strategy places orders on OKX by its rules.

Before connecting a real account, paper trade for a while. No key needed, and you start with 100,000 USDT.

Download the desktop app

For the full steps, see Set Up Exchange Trading Keys. For the whole path from idea to going live, see OKX Auto Trading: From Idea to Backtest to Live.

FAQ

Do API keys expire?
A key with an IP bound doesn't expire from inactivity. A key with trade or withdrawal permission and no IP bound is deleted after 14 days of inactivity.

What if I forget the passphrase?
It can't be recovered. Delete the key, create a new one, and paste the three new values back into the program.

When during the day do orders time out most?
OKX advises avoiding 8:00, 16:00 and 24:00 (Taiwan time, UTC+8) each day. Those are the funding settlements, when server load peaks.

Risks first

An API key is trading authority over your account, so don't paste it into sites or programs you don't trust. Never enable Withdraw, and delete keys you no longer use. Auto trading doesn't make losses go away. It only follows the rules. Leverage magnifies losses too.