> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OKX — Setup and Operation

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

<Info>
  **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.
</Info>

## When OKX makes sense

<CardGroup cols={2}>
  <Card title="Symbol coverage Bybit and Binance don't have" icon="boxes-stacked">
    OKX lists some Asian-market-driven symbols and certain altcoins where it has competitive liquidity. Useful for operators wanting that coverage.
  </Card>

  <Card title="Deep liquidity on majors" icon="droplet">
    OKX's `BTC-USDT` and `ETH-USDT` order books are deep and tight. Comparable to Bybit on majors.
  </Card>

  <Card title="Alternative second venue" icon="puzzle-piece">
    If Bybit doesn't fit your jurisdiction or preferences, OKX is the natural alternative second venue.
  </Card>

  <Card title="Multi-venue diversification" icon="globe">
    For operators running 3+ venues, OKX is a common third addition after Binance and Bybit.
  </Card>
</CardGroup>

## OKX's unique setup requirement: the passphrase

<Warning>
  **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.
</Warning>

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

<Steps>
  <Step title="Sign up at OKX">
    Standard signup flow. Use a referral link if available — lifetime fee discounts attached at signup.
  </Step>

  <Step title="Verify email and phone">
    Standard verification.
  </Step>

  <Step title="Complete KYC">
    KYC to the level required for spot trading. Higher tiers unlock features (margin, options) that unCoded does not need.
  </Step>

  <Step title="Enable 2FA">
    Authenticator app preferred over SMS.
  </Step>
</Steps>

## API key creation

<Steps>
  <Step title="Navigate to API settings">
    Go to "API" in account settings.
  </Step>

  <Step title="Click 'Create API Key'">
    The standard flow.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Connecting unCoded to OKX

<Steps>
  <Step title="Open the unCoded Dashboard">
    Log in with admin credentials.
  </Step>

  <Step title="Add OKX as an exchange">
    "Exchanges" → "Add Exchange" → "OKX."
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Watch the logs">
    Open Logs panel for the first hour to confirm normal operation.
  </Step>
</Steps>

## OKX-specific quirks

<AccordionGroup>
  <Accordion title="Symbol naming uses dashes" icon="font">
    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.
  </Accordion>

  <Accordion title="The passphrase requirement" icon="lock">
    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.
  </Accordion>

  <Accordion title="Signing scheme" icon="key">
    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.
  </Accordion>

  <Accordion title="Rate limits" icon="gauge">
    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.
  </Accordion>

  <Accordion title="Sub-account support" icon="layer-group">
    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.
  </Accordion>

  <Accordion title="Account modes — Cash, Single-currency margin, Multi-currency margin, Portfolio" icon="filter">
    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.
  </Accordion>
</AccordionGroup>

## Troubleshooting OKX-specific

<AccordionGroup>
  <Accordion title="Authentication fails with valid-looking credentials" icon="circle-exclamation">
    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).
  </Accordion>

  <Accordion title="Connection works but no orders fire" icon="circle-question">
    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?
  </Accordion>

  <Accordion title="Symbol not found errors" icon="font">
    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.
  </Accordion>

  <Accordion title="I lost the passphrase" icon="lock">
    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.
  </Accordion>

  <Accordion title="Account is in margin mode but I want spot only" icon="filter">
    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.
  </Accordion>
</AccordionGroup>

## Best practices for OKX operators

<Tip>
  * ✅ **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.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="API Key Security" icon="shield" href="/exchanges/api-key-security">
    Universal principles applicable to OKX.
  </Card>

  <Card title="Binance Setup" icon="building-columns" href="/exchanges/binance">
    The recommended primary venue most multi-venue operators run alongside OKX.
  </Card>

  <Card title="Bybit Setup" icon="building-columns" href="/exchanges/bybit">
    Alternative second venue without the passphrase requirement.
  </Card>

  <Card title="Other venues" icon="ellipsis" href="/exchanges/other-venues">
    Including BitMart, which uses a similar 'API\_UID' field requirement.
  </Card>

  <Card title="TradingBot" icon="robot" href="/modules/tradingbot">
    The execution engine that uses your OKX credentials.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting/common-issues">
    Every OKX error code and recovery procedure.
  </Card>
</CardGroup>