OKX API Key Invalid IP Whitelist: How to Fix Sub-Account Bot Connection Failed (2026)

# OKX API Key Invalid IP Whitelist: How to Fix Sub-Account Bot Connection Failed (2026)

Your bot usually fails for a simple reason: the API key was created correctly, but the machine calling OKX is not the machine OKX thinks it should trust.

That is why the error often appears right after setup. You create a sub-account, generate an API key, paste the key into a bot, press connect, and get some version of invalid IP, IP whitelist mismatch, or bot connection failed.

Based on OKX’s public API guide, API security guidance, and sub-account help documentation, the fastest way to fix this is to stop treating it like a strategy problem. This is almost always an account-binding problem or a connector configuration problem.

This guide walks through the shortest path to a fix, the common root causes, and the clean setup that prevents the same failure from coming back next week.

If you still need an account, you can sign up on OKX. This article contains affiliate links, which means we may earn a commission at no extra cost to you.

The short answer

When an OKX bot says invalid IP whitelist or fails to connect after key creation, check these in order:

1. confirm the API key was created on the correct sub-account

2. confirm the bot is using the same API key, secret, and passphrase that belong to that sub-account 3. confirm the bot’s actual public IP matches the IP allowlist on the key 4. confirm the key has the right permissions for the bot you are running 5. confirm you did not move the bot from one server, laptop, or hosted platform to another without updating the key 6. rotate the key if the passphrase, account binding, or IP history is messy

If you want the safest default setup, keep one bot on one sub-account, use Read + Trade only if the bot really places orders, leave Withdraw off, and bind the key to the exact machine that runs the bot.

What this error usually means in practice

Traders often read the message too literally.

They assume invalid IP whitelist means only one thing: “I typed the wrong IP.” Sometimes that is true. A lot of the time, the real issue sits one layer deeper.

In practice, the error usually points to one of these situations:

• the API key is bound to a different public IP than the one your bot is using now
• the key was created on the main account, while the bot is trying to operate inside a sub-account workflow
• the bot is calling from a hosted service or VPS whose public IP is different from your local machine
• the connector saved an old passphrase or secret while you updated only one field
• the key permissions are too narrow for the action the bot is trying to perform

That is why this is a troubleshooting article, not another generic API setup page. The key often exists. The problem is that the environment around it drifted.

Why sub-account bots hit this error so often

OKX’s public help pages frame sub-accounts as a way to separate strategies and manage risk. That design is good for live trading. It also creates one extra place where setup drift can happen.

Here is the common sequence:

• you create a new sub-account for a bot
• you transfer a small amount of capital into it
• you create a fresh API key
• you paste the credentials into a connector
• you later switch from local testing to a VPS, or from one bot platform to another
• the new machine has a different public IP, but the old allowlist stays in place

The bot now has valid credentials and still cannot connect.

That is healthy from a security perspective. It means the IP restriction is doing its job. The issue is operational discipline, not exchange instability.

If you want the wider account-structure logic first, read OKX Sub-Account API Key Permissions: How to Isolate Bot Risk Safely (2026).

Fix checklist: start here before you change anything else

Do this in order. It is the shortest route to a clean diagnosis.

1) Confirm which account actually owns the key

This is the first check because it invalidates everything else if you got it wrong.

Open the OKX account area where you manage API keys and verify that the key belongs to the specific sub-account your bot should use.

A lot of failed setups come from a simple mismatch:

• funds are sitting in a sub-account
• the bot is configured for that strategy
• the API key was actually created under the main account

That setup creates confusion fast. The connector may authenticate, then fail on trading or balance operations. In other cases, the user thinks the IP is wrong because the bot fails immediately after connection.

If the account context looks messy, fix it with a fresh key on the intended sub-account.

2) Verify the full credential set, not just the API key

An OKX API connection needs three pieces to line up:

• API key
• secret key
• passphrase

Based on OKX’s public API FAQ, the passphrase is part of the credential set and should be stored carefully because it cannot simply be recovered later.

That means a connection failure can come from a stale passphrase even when the API key itself is correct.

A clean rule helps here:

> Never update only one credential field inside a bot connector unless you are certain the other two still match the same key.

If you have copied credentials across test scripts, hosted bots, and environment files, treat partial edits as suspicious.

3) Check the bot’s real public IP

This is the core whitelist step.

The IP that matters is the public outbound IP of the machine that sends the API request.

That may be:

• your VPS public IP
• your office network public IP
• your home router public IP
• the outbound IP used by a hosted automation platform

It is usually not the private local address you see inside your laptop settings.

It is also often different from the IP you expect if:

• you moved from local testing to a cloud server
• your cloud provider rebuilt or replaced the instance
• your ISP changed your home IP
• your connector sends traffic through the provider’s infrastructure rather than your own machine

If you changed infrastructure after creating the key, the allowlist is your first suspect.

4) Compare that public IP to the key’s allowlist

Now check whether the exact current public IP is present on the API key.

Treat this as a strict string match problem.

Do not assume:

• “same city” means same IP
• “same VPS provider” means same IP
• “same account” means same IP
• “same bot platform” means same IP

For a live bot, the correct question is simple:

> Is the machine that sends this request listed on the key right now?

If the answer is unclear, update the allowlist or create a fresh key with the correct binding.

5) Confirm the permissions match the bot’s job

OKX’s public API help materials separate permissions such as Read, Trade, and Withdraw.

That matters because some connectors “test” the connection with endpoints that go beyond balance reading.

Examples:

• a dashboard bot may only need Read
• an execution bot usually needs Read + Trade
• almost no normal trading bot needs Withdraw

If a connector tries to place, amend, or cancel orders while your key only has Read permission, the connection test can look like a general bot failure even though the real issue is missing permission scope.

If your bot is meant to trade, check that the key actually has trading permission.

If your bot only monitors, reduce it to Read only and remove unnecessary risk.

The five most common root causes

Once you run the checklist, most failures fall into one of these buckets.

1. You whitelisted the wrong machine

This is the most common one.

Typical version:

• you created the key from your laptop
• you added your laptop network IP
• the bot actually runs on a VPS
• OKX receives requests from the VPS IP
• the whitelist blocks the call

Fix: whitelist the machine that makes the request, then retest.

2. Your public IP changed after setup

This happens a lot with home internet and occasionally with cloud rebuilds.

Your bot can run for days or weeks, then fail “suddenly” even though nothing in the trading logic changed.

That often means the strategy is healthy and the network identity changed.

Fix: confirm the machine’s current outbound IP and update the key or rotate to a fresh key.

3. The key belongs to the wrong OKX account layer

Sub-account workflows break cleanly when the key and the strategy account are not aligned.

Typical version:

• you meant to isolate one bot in one sub-account
• you created the key under a different account context
• the connector now reads one environment and tries to trade another

Fix: create the key again on the exact sub-account that will hold the bot capital.

4. The connector saved stale credentials

This is common after “quick fixes.”

You rotate the API key, paste the new key, forget the old passphrase is still stored, and the connector reports a generic failure.

Fix: clear all three credential fields and enter the full set again from the same key creation event.

5. The bot platform uses a different outbound IP than you expected

Hosted bot tools can confuse users here.

You may think “my bot runs in the cloud” is enough detail. It is not.

The exact outbound IP still matters. If the platform does not tell you the IP range clearly, your setup will stay fragile.

Fix: use a platform that documents its outbound IPs clearly, or move the bot to infrastructure you control directly.

The cleanest way to fix the problem

If the key history is messy, the fastest route is usually rotation, not endless tweaking.

Use this recovery pattern:

Option A: quick repair

Use this only when you are sure the account context is already correct.

• keep the same sub-account
• update the IP allowlist to the actual current public IP
• verify the permissions
• re-enter the full credential set in the bot
• test with the smallest possible action first

Option B: clean reset

Use this when multiple things may be wrong.

• revoke the questionable key
• create a fresh key on the intended sub-account
• set only the required permissions
• add the correct IP allowlist immediately
• store the key, secret, and passphrase together in one clean record
• reconnect the bot once

Option B is usually better for live capital because it removes hidden drift.

A safer setup that prevents repeat failures

The strongest prevention is architectural, not cosmetic.

Based on OKX’s public sub-account and API guidance, the safer operating model looks like this:

One bot, one sub-account

That gives you:

• clean capital isolation
• cleaner P&L tracking
• simpler API ownership
• faster incident response

One key per bot workflow

That means:

• one bot instance
• one key family
• one clear permission scope
• one clear allowlist

Do not use one key across multiple unrelated strategies if you want troubleshooting to stay simple.

Minimal permissions

For most live bots:

• Read + Trade is enough
• Withdraw stays off

For monitor-only workflows:

• Read only is enough

Stable infrastructure

If your IP changes often, the right fix is usually infrastructure discipline:

• use a VPS with a stable public IP
• keep one live environment per bot
• avoid bouncing between home laptop, test server, and hosted tool without rotating keys

That solves both security and reliability.

What traders should do before their next live test

Before you let the bot place real orders, run a short preflight check.

Preflight checklist

• correct sub-account selected
• correct API key, secret, and passphrase entered together
• current public IP confirmed
• key allowlist updated
• permissions matched to the bot’s job
• smallest possible test action completed successfully

If you pass that checklist, the next failure is much more likely to be inside the bot logic itself.

That is where strategy debugging belongs.

When the problem is not the whitelist

Sometimes the IP error distracts from a more general connector issue.

If the allowlist is correct and the bot still fails, check these next:

• wrong passphrase saved in the bot
• wrong API environment selected by the connector
• stale credentials cached by the bot platform
• missing trade permission on a live execution bot
• account mismatch between the exchange sub-account and the strategy configuration

That is why a key rotation often fixes more than one issue at once.

Should you remove the IP whitelist to make setup easier?

For a live trading bot, that is a bad trade.

OKX’s public API security guidance treats IP restriction as a core control. The practical reason is obvious: if the key leaks, IP binding gives you one more wall between a leaked credential and a real loss.

Removing the whitelist may get the bot online faster today. It also gives future mistakes a much larger blast radius.

The better path is:

• keep the whitelist
• stabilize the environment
• rotate keys when the environment changes

That is the setup that stays usable in production.

If you also need to understand how OKX handles transfers and permissions between main and sub-accounts, read OKX Sub-Account Withdrawal and Transfer Permissions: How to Move Funds Safely Between Main and Sub-Account (2026).

Final verdict

If your OKX bot says invalid IP whitelist, the highest-probability fix is to treat it as an identity mismatch: wrong machine, wrong sub-account, wrong credential set, or wrong permission scope.

The clean production setup is simple:

• one bot
• one sub-account
• one fresh key
• one stable IP
• minimum required permissions

That structure fixes the current error and makes the next one easier to diagnose.

If you are building your bot stack from scratch, sign up on OKX, create the sub-account first, and bind the API key to the machine that will actually run the strategy.