OKX Funding Account vs Trading Account: The Account Structure to Know Before You Automate

One OKX login has several layers underneath it. The funding account handles deposits and withdrawals, and the trading account handles orders, positions and margin. Money you put into a trading bot is isolated from the trading account, and every sub-account has a funding account and a trading account of its own. An API key belongs to the master account or to one sub-account, not to the funding or the trading account, and what it can do depends only on its permissions.

What's the difference between the funding and trading accounts?

A script's orders draw on the trading account, and withdrawals only cover assets in the funding account, so check which side the money is on first. Moving it between the two is a funds transfer, done inside OKX. Which account to pick when you deposit, how to call the transfer endpoint and what permission it needs are covered in OKX Funds Transfer: Where Deposits Land.

OKX's Get account asset valuation endpoint returns one account's assets in three places: the funding account, the trading account and the earn account. The first two are the ones a script deals with:

Is the money still in my trading account once a grid bot is running?

Not as available balance. According to OKX's Introduction to Trading bot Mode, once a spot grid is created its initial funds are isolated from the trading account and used for grid trading only. Because that money has left, it no longer backs any other positions you hold in the trading account.

When a script and a bot share one trading account, size orders from the available balance only, not from total equity. Where to see the money a bot is holding, and how to get it back, is covered under How do I see the funds a trading bot is holding?

Can a sub-account keep strategy money separate?

Yes. Each sub-account has its own funding account and trading account: the docs give the master account two separate endpoints for reading them, Get sub-account trading balance and Get sub-account funding balance.

Money moves between master and sub-accounts through the funds transfer endpoint. Which directions need the master account's key and which need the sub-account's key is set out in the table in the transfer article.

Putting a strategy's money in its own sub-account means a faulty strategy can only reach that share. The separation only holds if the strategy runs on the sub-account's own key, for reasons covered in What Happens When an API Key Leaks.

Which account does an API key belong to?

It belongs to the master account or to one particular sub-account, not to the funding or the trading account. The same key can call funding-account endpoints under /api/v5/asset/ and trading-account endpoints under /api/v5/account/ and /api/v5/trade/; what it may do depends only on its permissions. The docs list three permissions:

• Read: "Can request and view account info such as bills and order history which need read permission".
• Trade: "Can place and cancel orders, funding transfer, make settings which need write permission".
• Withdraw: "Can make withdrawals".

Note that Trade includes "funding transfer": a key with Trade permission can already move money between the funding account, the trading account, and master and sub-accounts. A sub-account's key is created by the master account, and the Create an API Key for a sub-account endpoint accepts only read_only and trade as permission values. There is no withdraw option.

If you can't tell whether a key is a master or a sub-account key, call Get account configuration: when uid equals mainUid it's the master account, otherwise a sub-account. Demo trading is a separate set: the docs require the API key for demo trading to be created inside demo trading, so you need another key there. The steps from creating a key to placing a first order are in the OKX API Quant Starter.

How does account mode decide the tdMode order parameter?

The Account mode section of the docs says: "4 account modes are supported: Spot mode, Futures mode, Multi-currency margin mode, and Portfolio margin mode." The first-time setting has to be made on the website or in the app. The acctLv field returned by Get account configuration is this setting: 1 is Spot mode, 2 Futures mode, 3 Multi-currency margin, 4 Portfolio margin.

What goes into tdMode (trade mode), which you have to specify on every order, follows the account mode. The notice under Place order lists it like this:

The same BTC-USDT spot buy takes cash on a Spot mode account and, per the docs, cross on a Multi-currency margin account. A script with tdMode hard-coded needs that line revisited whenever you switch accounts or change the account mode.

What to check before the script goes live

1. Call Get account configuration and read uid and mainUid (is this key on the master or a sub-account?) and acctLv (the account mode).
2. Query the funding balance and the trading balance once each, and confirm the money is on the side you intend to use.
3. If it's in the funding account, transfer it to the trading account first; the parameters, and how to confirm the result, are in the transfer article.
4. If a grid or another bot is running in the same trading account, work out your usable funds from the available balance (availBal).
5. Set tdMode from the table above, and verify with one small order in demo trading first.

FAQ