OKX Sub-Account API Key Permissions: How to Isolate Bot Risk Safely (2026)

If you run a trading bot on OKX, the most dangerous mistake is not a bad entry.

It is giving the bot too much access.

A lot of traders create one API key on the main account, check every permission they think they might need, paste it into a bot, and move on. That is the fastest way to turn a small automation mistake into a full-account problem.

Based on OKX's public sub-account and API documentation, the safer design is straightforward:

• keep your main account separate
• create a dedicated sub-account for the bot
• generate a separate API key for that sub-account
• enable only the permissions the bot actually needs
• bind the API key to trusted IP addresses
• keep the allowlist current if you move servers or add failover nodes
• avoid withdrawal permission unless there is a very specific operational reason

That structure does not make a bad strategy profitable. But it does reduce the blast radius when a script misfires, a connector breaks, or a third-party tool gets compromised. Disclosure: This article contains affiliate links. If you sign up through them, we may earn a commission at no extra cost to you.

The short answer

If you want the safest default setup for an OKX bot, do this:

1. Open or use your main OKX account for deposits, withdrawals, and long-term holdings.

2. Create one sub-account per bot or strategy. 3. Transfer only the capital that strategy is allowed to risk. 4. Create an API key inside that sub-account, not on the main account. 5. Turn on Read and Trade only if the bot needs both. 6. Leave Withdraw off in almost every case. 7. Add an IP allowlist for the exact server or machine running the bot. 8. Delete unused keys and rotate keys when infrastructure changes.

If you only remember one line from this guide, make it this:

> The safest OKX bot key is a sub-account key with the smallest possible balance, the fewest possible permissions, and a strict IP allowlist.

Why sub-accounts matter more than people think

A sub-account is not just an organizational feature. It is a risk boundary.

Based on OKX's help documentation, sub-accounts are designed to let users:

• separate trading strategies
• manage multiple bots
• control risks independently

That wording matters. It means OKX itself frames sub-accounts as a risk control tool, not just as an account convenience.

For bot trading, that gives you three protections that a single main-account API key cannot give you cleanly.

1. Capital isolation

If the bot only has access to one sub-account, it can only trade the funds inside that sub-account.

That means:

• your main holdings are separate
• your manual trading balance is separate
• another strategy's capital is separate

If the bot loops bad orders, mis-sizes a position, or runs on the wrong market, the damage is contained to the capital you intentionally placed in that sub-account.

2. Cleaner permissions

A sub-account key is easier to scope.

Instead of asking, "What permissions can I safely give on my whole OKX account?" you ask a narrower question:

> "What permissions does this one bot need inside this one isolated trading environment?"

That leads to better decisions.

3. Better operational visibility

If one sub-account equals one strategy, your audit trail gets easier to read:

• which positions belong to which system
• which API key belongs to which bot
• which P&L belongs to which workflow
• which connector should be disabled if something breaks

That clarity matters in an incident. When something goes wrong, speed comes from not having to untangle a shared mess.

What API permissions OKX offers

Based on OKX's public API FAQ and sub-account/API help pages, the core API permissions are:

• Read — allows reading account data
• Trade — allows sending and canceling orders
• Withdraw — allows withdrawals through the API

Those permissions are not morally equal.

They have very different risk profiles.

Read permission

This is the lowest-risk permission of the three.

Use it when your tool needs to:

• read balances
• check open positions
• monitor fills
• pull trade history
• sync portfolio dashboards
• generate reports or alerts

If a tool only needs reporting or monitoring, Read-only is the right answer.

Do not add Trade just because you might automate later.

Trade permission

Trade permission is what a real bot usually needs.

It allows the bot to:

• place orders
• amend orders
• cancel orders
• manage positions through supported trading endpoints

That means a Trade-enabled key can lose money very quickly if the bot logic is wrong.

Trade permission is still normal and acceptable for automation. But once you enable it, account isolation matters a lot more.

Withdraw permission

This is the one most traders should leave off.

OKX's own documentation labels withdrawal permission with caution, and that is the correct default attitude.

For most bot setups, a strategy bot does not need to:

• move funds off the platform
• push funds to a wallet
• handle treasury operations

If the bot's job is trading, then trading permission is enough.

The moment you add withdraw permission, you are no longer just exposing trading logic. You are exposing fund movement.

For a standard trading bot, that is usually unnecessary risk.

The safest default permission set for most bots

For most OKX bot users, the right setup is one of these two patterns.

Pattern A: monitoring, journaling, analytics, or signals only

Use:

• Read only

This fits:

• dashboards
• trade journals
• position monitors
• notification bots
• signal observers that do not place orders

Pattern B: real execution bot

Use:

• Read + Trade
• Withdraw off

This fits:

• custom execution bots
• rebalancers
• signal-to-order automations
• market-making or grid-style scripts
• strategy engines that place and cancel orders

Pattern C: treasury or managed operational workflows

Use only if there is a real need:

• Read + Trade + Withdraw

This should be rare.

If you run this pattern, you should assume you now need extra controls around:

• address whitelisting
• device security
• approval flow
• key storage
• operational monitoring

For the average trader running a bot from a VPS or local machine, Pattern C is overkill and avoidable.

Why IP allowlisting is not optional

OKX's API help pages explicitly recommend restricting API usage to trusted IP addresses, and the API FAQ says you can bind multiple IPs to a key.

Treat that as mandatory, not as a nice extra.

An IP allowlist changes the security model from:

> "Anyone with the key can use it from anywhere"

to:

> "Even if the key leaks, it should only work from the approved machine or server."

That is one of the highest-value security controls available in the setup.

When IP binding matters most

It matters especially when you use:

• a cloud VPS
• a hosted bot platform
• a third-party connector
• a dedicated home server with stable IP

If you know where the bot runs, bind the key to that IP.

A practical rule

If your bot has Trade permission and your API key is not IP-restricted, fix that before you optimize anything else.

A perfect strategy with a sloppy key setup is still sloppy.

A safe OKX bot architecture that actually makes sense

Here is the cleanest structure for most traders.

Main account

Use the main account for:

• external deposits
• external withdrawals
• long-term holdings
• manual account management
• products the sub-account may not support

Sub-account 1: Bot A

Use it for:

• one specific strategy
• one API key or one key family
• one limited balance

Permissions:

• Read + Trade
• no Withdraw
• IP allowlist enabled

Sub-account 2: Bot B

Use it if you run a second strategy with different logic or risk.

Examples:

• one sub-account for a market-making bot
• another for swing execution
• another for paper-to-live migration of a new system

This avoids a common problem: profitable bots hiding the losses of broken bots in the same balance pool.

How much capital should you keep in a bot sub-account?

As little as needed for the strategy to function properly.

That is the operational answer.

A sub-account should not become a shadow main account.

If a bot needs $2,000 of margin to run safely, put roughly that amount there, not your whole exchange balance.

The point of the sub-account is not just to label the strategy. The point is to cap the downside of automation failure.

A useful way to think about it:

• the main account is treasury
• the sub-account is the strategy sandbox

Fund the sandbox. Do not move the whole treasury into the sandbox.

Step-by-step: how to set up OKX sub-account API permissions safely

Based on the public OKX workflow, here is the clean sequence.

1) Create the sub-account first

On the OKX website:

• sign in
• go to Profile → Sub-accounts
• choose Create sub-account
• confirm creation with 2FA

Standard users can create up to five sub-accounts (as of 2026-04), based on the current OKX help documentation.

That is enough for most traders to separate live bots, experiments, and manual activity.

2) Transfer only the strategy budget

Move funds internally from the main account into the new sub-account.

Do not start by transferring a large general-purpose balance just because it is convenient.

A good question here is:

> "If this bot malfunctioned tonight, what is the maximum amount I am willing to have exposed?"

That number is the sub-account funding limit.

3) Create the API key on the correct account

When you create the API key in OKX, choose the sub-account you want to use.

OKX's API help page notes that the account selector becomes relevant when sub-accounts are linked. That means you should confirm you are generating the key for the intended sub-account, not accidentally for the main account.

This is the most important setup step.

If you skip it and create the key on the main account, you lose most of the risk-isolation benefit.

4) Select only the required permissions

Choose one of these:

• Read only, or
• Read + Trade

Leave Withdraw off unless your workflow genuinely requires API withdrawals.

For most bot traders, it does not.

5) Add the IP allowlist

Enter the IP address or addresses of the machine that will call the API.

Examples:

• your VPS public IP
• your office static IP
• your home fixed IP if you run the bot locally

If your IP changes often, solve that infrastructure problem instead of simply removing the allowlist.

Convenience is not a good trade if it removes one of your strongest security controls.

6) Save the passphrase carefully

OKX's API FAQ is clear on this point: the passphrase cannot be recovered if lost.

That means you need a clean storage process for:

• API key
• secret key
• passphrase

Losing the passphrase is not a security disaster, but it is an operational one. You will have to rotate and replace the key.

Two OKX API details that change the setup in practice

These two details are easy to miss in the docs, and both matter in live operations.

1) The passphrase is permanent for that key

OKX's API FAQ says the passphrase cannot be recovered.

That means your API credential set is really four items, not three:

• API key
• secret key
• passphrase
• allowed IP list

If you lose the passphrase, the recovery path is simple:

• create a new key
• update your bot or connector
• revoke the old key

Treat the passphrase like production infrastructure, not like a note you can recreate later.

2) Unbound trade or withdraw keys can disappear after inactivity

OKX's API FAQ also says API keys that are not bound to IP and have trade or withdraw permissions are automatically deleted after 14 days of inactivity (as of 2026-04).

This matters for three common setups:

• a bot you only use occasionally
• a failover key you created and forgot
• a connector key sitting idle while you test elsewhere

The practical answer is straightforward:

• bind live keys to trusted IPs
• avoid keeping extra trade-enabled keys around unused
• review old keys before they surprise you or disappear

For most live bot setups, IP binding is already the safer security choice. This inactivity rule makes it the cleaner operational choice too.

7) Test with the smallest possible trade size

Before funding more capital or letting the bot run unattended:

• check balance reads
• place a tiny test order
• confirm order status updates
• confirm cancel/amend logic works
• verify symbol and account-mode handling

The goal is not to prove the strategy wins. The goal is to prove the plumbing is correct.

Which permission set fits which bot

The fastest way to overscope a key is to think in features instead of workflows.

This mapping is the cleaner way to decide.

Bot or tool type	What it actually does	Recommended permissions	Best account home
Dashboard / reporting tool	Reads balances, positions, fills, history	Read	Main or sub-account
Journal sync / analytics	Pulls fills, PnL, balances, export data	Read	Sub-account
Alert bot with no execution	Watches markets or account state and sends alerts	Read	Sub-account
Live execution bot	Places, amends, cancels orders	Read + Trade	Dedicated sub-account
Rebalancer / DCA automation	Places scheduled spot or conversion trades	Read + Trade	Dedicated sub-account
Treasury workflow	Moves funds or handles payout operations	Read + Trade + Withdraw only with explicit need	Dedicated treasury sub-account

If you are unsure between two rows, pick the lower-permission row first and expand only when the workflow proves it needs more.

Third-party apps: use the whitelist path when the connector supports it

OKX's third-party app IP whitelist workflow exists for a reason.

When a broker or external platform supports OKX's whitelist integration, the safer path is:

• create the key for Binding third-party apps
• select the supported app from the dropdown
• let OKX limit usage to that provider's whitelisted servers

That gives you a stronger setup than pasting a generic trade-enabled key into a connector with no IP boundary.

For self-hosted bots, your own server IP allowlist is the right answer.

For supported third-party apps, the built-in whitelist flow is the cleaner answer.

Common bad setups to avoid

A lot of risk comes from architecture, not from code.

Here are the common bad patterns.

Bad setup #1: Main account API key for a third-party bot

This is the classic mistake.

You connect a third-party bot platform to your main account, give it broad permissions, and hope the platform is careful.

That exposes:

• more capital than necessary
• more strategies than necessary
• more operational surface than necessary

Use a sub-account instead.

Bad setup #2: One API key for multiple bots

If multiple systems share one key, then:

• debugging gets harder
• revoking access gets harder
• logging gets noisier
• incident containment gets weaker

Use one strategy environment per key or per tightly grouped workflow.

Bad setup #3: Trade permission for a reporting tool

If a dashboard, spreadsheet connector, or alerting service only needs to read balances, do not give it Trade permission.

This is pure avoidable risk.

Bad setup #4: No IP allowlist because the IP changes

This usually means your infra is not stable enough yet for live automation.

Fix the infrastructure. Do not weaken the key.

Bad setup #5: Leaving old keys active forever

Unused keys are hidden liabilities.

If a bot is retired, a server is replaced, or a connector is no longer used, revoke the old key.

What happens if you really need withdrawal permission?

Some professional or managed workflows may require it. OKX's documentation around managed trading sub-accounts shows that withdrawals can be paired with verified-address controls and specific configuration.

But for a normal self-directed trading bot, that is usually the wrong place to start.

If you truly need withdrawal permission, the minimum standard should be:

• dedicated sub-account only
• whitelisted destination addresses only
• IP allowlist enabled
• separate operational key from trading key if possible
• active monitoring and human review

That is a different risk class from "my bot needs to place trades."

Do not confuse them.

A simple permission matrix you can copy

| Use case | Account | Permissions | Withdraw | IP allowlist |

|---|---|---:|---:|---:| | Portfolio dashboard | Sub-account or main | Read | No | Yes | | Trade journal sync | Sub-account | Read | No | Yes | | Signal monitor | Sub-account | Read | No | Yes | | Live execution bot | Sub-account | Read + Trade | No | Yes | | Managed operational treasury workflow | Dedicated sub-account | Read + Trade + Withdraw | Only if required | Yes |

That table is boring, which is exactly why it works.

Safe infrastructure is usually boring.

IP allowlist checklist before you call the setup finished

OKX's API FAQ says you can link up to 20 IP addresses per key (as of 2026-04).

That gives you enough room for a practical production setup like:

• one primary VPS
• one backup VPS
• one office or home admin IP
• one staging box if you truly need it

A clean checklist looks like this:

• every live trade-enabled key is IP-bound
• old server IPs are removed after migration
• backup IPs are documented, not guessed from memory
• failover nodes use the same least-privilege permission logic
• keys you no longer need are revoked instead of kept "just in case"

The goal is a key that still works when you need controlled redundancy, while staying narrow enough that a leaked credential stays contained.

The real goal: making failure survivable

Bot risk is not only about "Will this strategy lose money?"

It is also about:

• what happens if the connector sends duplicate orders
• what happens if the account mode is wrong
• what happens if a server is compromised
• what happens if a bot loops on cancel/replace logic
• what happens if a third-party integration is less secure than you expected

A good sub-account and API permission setup does not eliminate those failures.

It makes them smaller, easier to detect, and easier to shut down.

That is the whole point.

If you care about automation longevity, survivability matters more than elegance.

Internal links worth reading next

If you are building an OKX automation stack, these pages fit naturally with this one:

• OKX Sub-Account vs Main Account: When You Actually Need One
• OKX Complete Beginner Guide: Register, KYC, First Deposit, First Trade
• AI Trading Agent Security Guide: How to Protect API Keys, Bots, and Funds
• OKX Agent Trade Kit OpenClaw AI Trading Setup Guide

Bottom line

If you run bots on OKX, your default setup should be:

• main account for treasury and withdrawals
• sub-account for each bot or strategy
• Read + Trade only when needed
• Withdraw off by default
• strict IP allowlist on every live key

That is the practical answer to "how do I isolate bot risk safely?"

Not more indicators. Not more prompts. Not a smarter VPS.

A narrower account boundary and tighter permissions.

If you do not have an OKX account yet, you can sign up on OKX and set up your account structure before your first bot goes live.

---

Affiliate disclosure: This page includes affiliate links. If you use them, we may earn a commission at no extra cost to you. Risk reminder: Crypto trading and API automation both involve significant risk. Test with small size first, and never give a bot more capital or permissions than it truly needs.