OKX — Setup and Operation

Strong global liquidity, broad symbol coverage, dash-separated symbol naming, and a unique passphrase requirement that adds a security layer.

OKX is a strong global venue with deep order books and broad symbol coverage. It has one operator-relevant peculiarity worth knowing upfront: API keys carry a passphrase in addition to key and secret. This is unique among the major venues unCoded supports — and it’s a small extra security layer at the cost of a small extra setup step.

When OKX makes sense

Symbol coverage Bybit and Binance don't have

OKX lists some Asian-market-driven symbols and certain altcoins where it has competitive liquidity. Useful for operators wanting that coverage.

Deep liquidity on majors

OKX’s BTC-USDT and ETH-USDT order books are deep and tight. Comparable to Bybit on majors.

Alternative second venue

If Bybit doesn’t fit your jurisdiction or preferences, OKX is the natural alternative second venue.

Multi-venue diversification

For operators running 3+ venues, OKX is a common third addition after Binance and Bybit.

OKX’s unique setup requirement: the passphrase

OKX is the only venue among the top supported exchanges that requires an API passphrase in addition to the API key and secret.

The passphrase is set at API key creation time (you choose the value). All three credentials — key, secret, passphrase — are needed for the bot to authenticate to OKX. Save all three immediately at creation.

If you lose any of the three, you cannot recover them. You’d have to revoke the key and create a new one with a new passphrase.

The passphrase is not your account password. It’s a per-API-key extra credential — a kind of second secret. Conceptually similar to a “salt” you add to the key. It exists to add a security layer: a leaked key + secret without the passphrase still cannot authenticate.

Account creation

1. Sign up at OKX

   Standard signup flow. Use a referral link if available — lifetime fee discounts attached at signup.

2. Verify email and phone

   Standard verification.

3. Complete KYC

   KYC to the level required for spot trading. Higher tiers unlock features (margin, options) that unCoded does not need.

4. Enable 2FA

   Authenticator app preferred over SMS.

API key creation

1. Navigate to API settings

   Go to “API” in account settings.

2. Click 'Create API Key'

   The standard flow.

3. Set a passphrase

   Choose a passphrase for this API key. This is not your account password — it’s a credential specific to this API key.

   Save this passphrase immediately. OKX will not show it to you again. Paste it into your password manager alongside the key and secret.

   Pick a long random string (a password manager can generate one). The passphrase is part of the cryptographic signing, so it doesn’t have to be human-memorable.

4. Configure permissions

   • ✅ Trade — select.
   • ❌ Withdraw — do not select. NEVER enable this.
   • ❌ Read-only — actually you do want read access, but in OKX’s UI it’s typically bundled with Trade. Verify the key can read account data.
5. Set IP allowlist

   IP Address Whitelist: paste your VPS’s static IP. Find it with curl -s https://api.ipify.org from the VPS.

   Wait 30–60 seconds for propagation after saving.

6. Save the key, secret, AND passphrase

   All three credentials are needed. Save all three to your password manager before doing anything else.

   The order of fields in OKX’s display is typically: API Key, Secret Key, Passphrase. Save each one.

Connecting unCoded to OKX

1. Open the unCoded Dashboard

   Log in with admin credentials.

2. Add OKX as an exchange

   “Exchanges” → “Add Exchange” → “OKX.”

3. Paste all three credentials

   The OKX form has three fields: API Key, Secret, and Passphrase. Paste all three.

   If your form is missing the passphrase field, ensure you’ve selected “OKX” specifically (not a different venue).

4. Save and test

   Click “Save,” then “Test Connection.”

   If success: connection is green. Proceed to allocating pairs.

   If failure: most often the passphrase was mistyped or has trailing whitespace. Re-paste carefully.

5. Watch the logs

   Open Logs panel for the first hour to confirm normal operation.

OKX-specific quirks

Symbol naming uses dashes

OKX pairs use dash-separated naming: BTC-USDT, ETH-USDT, SOL-USDT. Different from Binance/Bybit’s unhyphenated BTCUSDT.

The unCoded exchange profile handles this transparently — you specify pairs in the Dashboard and the bot uses the correct format in API calls. No operator action needed.

But: if you’re cross-referencing against Binance’s symbols mentally, remember the format difference. BTCUSDT on Binance = BTC-USDT on OKX.

The passphrase requirement

Already covered above, but worth re-emphasizing: every authenticated request to OKX includes the passphrase as part of the signing. Without it, the request fails authentication regardless of how correct the key/secret are.

Lose the passphrase and you cannot recover it — you must revoke the key and create a new one. The Dashboard’s connection state will show OKX as disconnected until credentials are corrected.

Signing scheme

OKX uses HMAC-SHA256 signing (or Ed25519 for some advanced flows). The unCoded exchange profile defaults are correct for the production API.

You don’t need to configure signing manually — the profile handles it.

Rate limits

OKX’s published rate limit is 60 requests per 2 seconds across many endpoint categories. unCoded’s exchange profile reserves headroom and operates well below.

If you see rate-limit errors, the bot’s cooldown-and-retry logic handles them automatically. Persistent rate-limit hits indicate a configuration too aggressive for the venue.

Sub-account support

OKX supports sub-accounts. Same pattern as Binance/Bybit: separate API keys per sub-account, separate balances, one master account for compliance.

If you go this route on OKX, remember each sub-account API key needs its own passphrase. Don’t reuse passphrases across sub-accounts.

Account modes — Cash, Single-currency margin, Multi-currency margin, Portfolio

OKX has multiple “account modes” that affect how positions are managed. For unCoded’s spot-only modes:

• Cash mode is the right choice. Pure spot trading.
• The other modes enable margin or futures features the bot doesn’t use.

Set your account to Cash mode in OKX settings. If you accidentally set a margin/futures mode, the bot will operate but with unnecessary complexity.

Troubleshooting OKX-specific

Authentication fails with valid-looking credentials

Most common cause: passphrase typo or whitespace.

Steps:

1. Re-copy the passphrase from your password manager (not from a chat or email).
2. Paste carefully — watch for trailing whitespace.
3. Save and retest.

Second most common: IP allowlist mismatch. Verify VPS IP matches OKX’s allowlist.

Third: key has wrong permissions (Trade not selected).

Connection works but no orders fire

Same diagnostic flow as other venues:

1. Kill switch off?
2. Pair in active set with the correct OKX symbol format (BTC-USDT, not BTCUSDT)?
3. Mode active for the pair?
4. Buy conditions actually triggering?
5. Min-notional rejections in logs?
6. Insufficient balance?

Symbol not found errors

If you specified the symbol in Binance format (BTCUSDT) when adding the pair, OKX doesn’t recognize it.

Fix: in the Dashboard, edit the pair and use OKX’s dash-separated format: BTC-USDT. The bot will then use the correct symbol in API calls.

I lost the passphrase

Recovery path:

1. At OKX, revoke the API key.
2. Create a new API key with a new passphrase.
3. Save all three credentials (key, secret, new passphrase) immediately.
4. Update unCoded Dashboard with the new credentials.
5. Restart the TradingBot if needed.

Going forward: store the passphrase in your password manager at creation. Don’t try to memorize it.

Account is in margin mode but I want spot only

Change OKX’s account mode to “Cash” in account settings. The bot’s spot-only operations will work cleanly without the margin-mode complexity.

Be aware: account mode changes can take effect at the next session. Some operators run a brief disconnect-reconnect cycle on the bot after the change.

Best practices for OKX operators

• ✅ Save all three credentials at creation — key, secret, AND passphrase. The passphrase is unrecoverable.
• ✅ Set the OKX account mode to ‘Cash’ for spot-only operation.
• ✅ API key permissions: Trade only, no Withdraw.
• ✅ IP allowlist your API key.
• ✅ Authenticator app for 2FA.
• ✅ Use OKX’s dash-separated symbol format (BTC-USDT) in the Dashboard — the bot uses what you specify.
• ✅ Pick a long random passphrase — generated by your password manager.
• ✅ Do not reuse passphrases across sub-accounts if you use sub-account isolation.
• ✅ Quarterly rotation — same cadence as your other venues.
• ✅ Monitor the Dashboard’s connection state for OKX — passphrase issues surface as disconnected status.

What’s next

API Key Security

Universal principles applicable to OKX.

Binance Setup

The recommended primary venue most multi-venue operators run alongside OKX.

Bybit Setup

Alternative second venue without the passphrase requirement.

Other venues

Including BitMart, which uses a similar ‘API_UID’ field requirement.

TradingBot

The execution engine that uses your OKX credentials.

Troubleshooting

Every OKX error code and recovery procedure.