Skip to main content

OKX API Setup (okx.com)

Connect KhunQuant to your OKX account for international crypto trading with USDT and other major pairs.

← Back to Exchange Overview

Before You Start​

Make sure you have:

  • An OKX account at okx.com
  • Identity verification (KYC) completed
  • Two-Factor Authentication (2FA) enabled — use an authenticator app
  • At least $100 USD equivalent in your OKX account (OKX requires a minimum balance before API creation is allowed)
Critical Safety Warning

When creating your API key, you will see a permission called "Withdraw". Never enable this. KhunQuant only needs Read and Trade access. If someone obtains your API key with withdrawal enabled, they could drain your entire account instantly.

Step 1 — Open API Management​

  1. Log in to okx.com
  2. Click your profile icon (top-right corner)
  3. Select [Account] from the dropdown
  4. In the left sidebar, click [API]
  5. Click [Create V5 API Key]

Step 2 — Fill in API Key Details​

You will see a form with several fields:

API Key Name — Enter a descriptive label:

  • KhunQuant
  • Portfolio-Tracker

Passphrase — This is a custom password you create yourself. It is NOT your OKX login password.

Passphrase — Read Carefully
  • The passphrase is a new password you invent just for this API key
  • OKX stores it as a salted hash — they cannot show it to you again
  • If you forget the passphrase, you must delete this key and create a new one
  • Write it down in your password manager immediately, alongside the API key and Secret key
  • Example of a strong passphrase: KhunQ-2026-MyOKX! (make your own unique one)

Step 3 — Set Permissions​

Configure permissions exactly as follows:

PermissionSettingReason
✅ ReadONRequired to view balances, orders, and market data
✅ TradeONRequired to place and cancel orders
❌ WithdrawOFF — NEVER ENABLECritical security risk
❌ Sub-account transferOFFNot needed
Read-only Mode

If you only want KhunQuant to track your portfolio without trading, you can enable only Read and leave Trade off. This is the most secure option if you don't need automated trading.

Step 4 — Set Up IP Whitelist (Strongly Recommended)​

Key Expiry Warning

OKX automatically expires API keys after 14 days if the key has Trade or Withdraw permissions and no IP whitelist is set. Your key will stop working and you'll need to create a new one. Always add an IP whitelist if you enabled Trade permission.

To find your IPv4 address: Go to https://whatismyipaddress.com/ and look for the IPv4 value (format: 123.456.789.0).

To add your IP:

  1. In the API creation form, find the "IP addresses (Optional)" field
  2. Enter your IPv4 address
  3. You can add up to 20 IP addresses (useful if you have multiple locations)
  4. Click Confirm
Dynamic IP — Local Computer Users

If KhunQuant runs on your home computer or laptop, your public IP address can change without warning — this happens when your router restarts or your ISP assigns you a new address. When that happens, OKX will reject your API key with an "IP not allowed" error. You will need to update the whitelist with your new IP.

If KhunQuant runs on a cloud server or VPS, use the server's static public IP instead — it won't change. Make sure your cloud instance or VPS is secured with a firewall so only you can access it.

Read-only? Safe to Skip IP Whitelisting

If you configured the API key with Read permission only (no Trade), it is safe to leave IP whitelisting off. A read-only key can only view your balance and market data — it cannot place or cancel orders. Your account remains secure enough without the IP lock, and you won't face the 14-day expiry rule either (it only applies to keys with Trade or Withdraw permissions).

Step 5 — Verify Your Identity​

Complete 2FA verification:

  1. Enter the 6-digit code from your authenticator app
  2. Click the email verification link sent to your registered email

Step 6 — Save Your Keys​

After confirming, OKX displays three values:

  • API Key — your identifier (can be viewed later)
  • Secret Key — ⚠️ Shown only once, then hidden forever
  • Passphrase — the custom password you created in Step 2

Copy all three immediately and store in a password manager. If you lose the Secret Key or forget the Passphrase, you must delete this key and create a new one.

Step 7 — Add to KhunQuant​

Recommended: Use the Web UI

Open KhunQuant's portfolio settings in your browser:

http://localhost:18800/portfolios/okx

Paste your API Key, Secret Key, and Passphrase into the form and click Save. KhunQuant automatically encrypts all three values with enc:// prefix — you never need to touch any config files.

Why Not Edit the File Directly?

If your .security.yml already uses encrypted fields (enc:// prefix), pasting plain credentials directly into the file will cause an authentication error at startup. The web UI handles encryption automatically and avoids this problem. This is especially important for OKX since you have three fields to manage.

Alternative: Manual file edit (advanced users only)

Open ~/.khunquant/.security.yml:

exchanges:
  okx:
    accounts:
      - api_key: "paste_your_api_key_here"
        secret: "paste_your_secret_key_here"
        passphrase: "paste_your_passphrase_here"

Open ~/.khunquant/config.json and enable OKX:

{
  "exchanges": {
    "okx": {
      "enabled": true
    }
  }
}

Restart KhunQuant. Try:

  • "What's my OKX balance?"
  • "Show BTC/USDT price on OKX"
  • "List my open OKX orders"

Troubleshooting​

ProblemSolution
"Invalid API key"Check for spaces in your YAML file — api_key, secret, and passphrase must all match exactly
"Passphrase incorrect"Re-check your passphrase. If forgotten, delete this key and create a new one
"IP not whitelisted"Your IP may have changed. Update the whitelist on OKX
Key stopped working after 14 daysNo IP whitelist was set. Create a new key and add an IP whitelist
"Insufficient balance" error during API creationOKX requires ~$100 USD minimum balance before API creation is allowed