OKX Using Demo API for the First Time? Key and Request Header Setup

The most important difference when using the OKX API for the first time is not how you fill in the API key, but which "hat" you put on your request — the real live trading environment or the demo environment for practice. These two environments are completely isolated. Keys cannot be shared between them, and you must use different request header parameters to tell them apart.

Step 1: Decide whether you need a live key or a demo key

This is the easiest step to mess up. OKX keeps live and demo API keys completely separate. One key cannot work for both environments.

• What to do: Create your API key in the correct environment based on your purpose.

• How to do it:

  • Live API Key: Log in to OKX and go to "Account" or "API" management (path: click the profile icon in the top right → API → Create API key).

  • Demo API Key: After logging in to OKX, you must first enter the Demo Trading page, then create a dedicated API key inside the demo environment. You cannot create it on the live API management page.

• Completion standard: You know exactly which environment your API key belongs to.

Common failure reason: Many people take a live API key and try to call a demo endpoint. The system returns error code 50101 (APIKey does not match the current environment). That's the cause.

Step 2: When using a demo key, you must add a specific request header

This is the core identifier for demo API calls. Without it, your request will be treated as live trading or rejected outright.

• What to do: Add a custom field to the HTTP header of your API request.

• How to do it: Include x-simulated-trading: 1 in the request header.

  • Demo: The request header must contain x-simulated-trading: 1.

  • Live: Use x-simulated-trading: 0 in the header, or simply omit this field (the system treats the request as live by default).

• Completion standard: Every authenticated demo request from your code or tool correctly includes this header.

Risk warning: Never hardcode your live Secret Key and Passphrase in your code, and never upload them to GitHub or any public place. Official documentation and community tutorials repeatedly stress: the Secret Key and Passphrase are shown only once when you create them. After you close the page, they cannot be retrieved. You must immediately save them in a safe place (a password manager is recommended). If your keys leak, others can operate your account through the API without needing your phone verification.

How to verify after setup

After creating the key and setting the request header, test with a read-only endpoint (like checking account balance) before placing any orders.

• Code example (using the python-okx library):

  from okx import Account
  # flag='1' means demo, flag='0' means live
  account = Account.AccountAPI(
  api_key="your_API_KEY",
  api_secret_key="your_SECRET_KEY",
  passphrase="your_PASSPHRASE",
  flag="1"  # 1 = demo trading, 0 = live trading
  )
  result = account.get_balance()
  print(result)

  (Source: python-okx SDK documentation)

Next step recommendation

If this is your first attempt, strongly recommend running the whole flow on the demo environment first. The official OKX tutorial clearly suggests: "For your first setup, always use the demo environment. Switch to live only after your strategy works." If possible, create a separate sub-account for the API so funds are isolated, limiting potential damage if something goes wrong.