Skip to main content

​
Create API keys

1

Generate your API key on OKX

Visit OKX API Management and create a new API key. OKX will generate three values that you need:
CredentialDescription
apiKeyPublic identifier for your key
apiSecretSecret used to sign requests — treat this like a password
apiPassPassphrase you chose when creating the key
Your apiSecret is only shown once at creation time. Store it securely immediately.
2

Store credentials in environment variables

Never hardcode credentials in source code. Use environment variables instead:
export API_KEY_COM='your-api-key'
export API_SECRET_COM='your-api-secret'
export API_PASSPHRASE_COM='your-api-passphrase'
Or pass them inline when running a script:
API_KEY_COM='your-api-key' API_SECRET_COM='your-api-secret' API_PASSPHRASE_COM='your-passphrase' ts-node my-script.ts
Use single quotes in the shell to prevent special characters like $ from being incorrectly interpolated.
3

Pass credentials to the client

Supply the three credential fields when constructing RestClient or WebsocketClient.
import { RestClient } from 'okx-api';

const client = new RestClient({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
});
WebsocketClient accepts an accounts array, which allows you to authenticate up to 100 accounts on a single private connection — matching OKX’s own limit.

​
Region selection

OKX operates three separate regional platforms, each with its own domain and API endpoint. API keys are created per platform and are not interchangeable between regions.
RegionDomainmarket value
OKX Global (default)www.okx.com'GLOBAL' or omit
OKX EEAmy.okx.com'EEA'
OKX USapp.okx.com'US'
Set the market option on either client to connect to the correct regional endpoint: 
import { RestClient } from 'okx-api';

const client = new RestClient({
  apiKey: process.env.API_KEY_EEA,
  apiSecret: process.env.API_SECRET_EEA,
  apiPass: process.env.API_PASS_EEA,
  market: 'EEA', // connects to my.okx.com
});
Global is the default. If you are on www.okx.com, you do not need to set market at all.

​
Demo trading mode

OKX provides a paper trading environment (“demo trading”) that uses separate demo keys but does not require real funds. This is the recommended way to test your integration before going live. Enable it by setting demoTrading: true on either client. Use your demo API keys — not your live keys. 
import { RestClient } from 'okx-api';

const client = new RestClient({
  apiKey: process.env.API_KEY_COM,     // demo API key
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
  demoTrading: true,
});

(async () => {
  const balance = await client.getBalance({ ccy: 'USDT' });
  console.log('Demo USDT balance:', JSON.stringify(balance, null, 2));

  const buyResult = await client.submitOrder({
    instId: 'BTC-USDT',
    ordType: 'market',
    side: 'buy',
    sz: '0.002',
    tdMode: 'cash',
    tgtCcy: 'base_ccy',
  });
  console.log('Demo buy result:', buyResult);
})();

​
Client options reference

The RestClientOptions interface (from src/types/rest/client.ts) and WSClientConfigurableOptions interface (from src/types/websockets/ws-general.ts) accept the following credential and authentication options:

​
RestClientOptions

OptionTypeDescription
apiKeystringYour OKX API key
apiSecretstringYour OKX API secret
apiPassstringYour OKX API passphrase
market'GLOBAL' | 'EEA' | 'US' | 'prod'Regional endpoint to connect to. Defaults to 'GLOBAL' (www.okx.com)
demoTradingbooleanSet to true to use OKX’s demo trading environment
baseUrlstringOverride the API base URL entirely (advanced use)
keepAlivebooleanEnable HTTP KeepAlive for REST requests
strict_param_validationbooleanThrow errors on undefined parameters when true

​
WSClientConfigurableOptions

OptionTypeDescription
accountsAPICredentials[]One or more { apiKey, apiSecret, apiPass } objects for private channel authentication
market'GLOBAL' | 'EEA' | 'US' | 'prod'Regional endpoint to connect to
demoTradingbooleanSet to true to use OKX’s demo trading environment
pingIntervalnumberHow often (ms) to check if the connection is alive
pongTimeoutnumberHow long (ms) to wait for a heartbeat reply before treating the connection as dead
reconnectTimeoutnumberDelay (ms) before respawning a dropped connection

​
Security best practices

Hardcoding credentials in source code is a serious security risk. Even in private repositories, credentials can be leaked through git history, CI logs, or accidental shares.
  • Use environment variables — load credentials with process.env and never commit them to version control.
  • Restrict API key permissions — create read-only keys for market data, and only grant trade/withdrawal permissions to keys that require them.
  • Rotate keys regularly — if a key is compromised, revoke it immediately from the OKX API Management page.
  • Use IP allowlisting — OKX lets you bind an API key to specific IP addresses, limiting exposure if a key is leaked.
  • Separate demo and live keys — keep demo trading keys distinct from production keys to avoid accidentally trading on a live account.

Build docs developers (and LLMs) love

Get started for freeTalk to us