Overview OKX.AI Wallet Payment Trade Market Exchange OS X Layer

Exchange OS Open API Conventions#

Welcome to the Exchange OS Open API.

This API aggregates perp and spot markets and provides external developers with unified REST, WebSocket, and trading-signature interfaces. Business lines are not distinguished by URL paths; they are routed through request parameters or assetId:

Write endpoints specify the market type through marketType.
Account and trading read endpoints usually derive the market type from assetId.
Market-instrument query endpoints can be filtered using marketType.

Base Path#

text

/api/v5/exchangeos/

Full URL:

text

https://{host}/api/v5/exchangeos/{endpoint}

Examples:

http

POST /api/v5/exchangeos/trade/place-order
GET /api/v5/exchangeos/market/instruments

Environment#

Environment	Base URL
Production	`https://www.okx.com`

Identifier Conventions#

Identifier	Description
`assetId`	Composite asset ID of type `String`. Its encoding includes the market type: `assetId % 100 == 1` indicates Spot, and `assetId % 100 == 2` indicates perp. Account and trading read endpoints routed by `assetId` do not require a separate `marketType`.
`tokenId`	Token ID of type `String`. The collateral token USDS has `tokenId` of `"0"`. Account endpoints consistently use `tokenId` to identify tokens.
`oid`	On-chain order ID as a decimal `String`. Regular orders are usually assigned by the matching engine. System orders, such as liquidation, ADL, or settlement orders, may use virtual `oid` values.
`clientOrderId`	User-defined order ID in the format `0x{region}{env}{30hex}`, for a total of 34 characters. Required for regular order placement. Trigger and TPSL orders must not include it. It can be used for cancellation, modification, and asynchronous result matching.

Units#

Order sizes for both perp and spot are denominated in Base Token units. Contract lots are not used.

Response Format#

All REST endpoints use the following response envelope:

json

{
  "code": "0",
  "msg": "",
  "data": []
}

Write Endpoint Authentication#

All write endpoints must include the following request headers:

Header	Description
`OK-ACCESS-KEY`	API Key.
`OK-ACCESS-SIGN`	Request signature: `Base64(HMAC-SHA256(timestamp + method + requestPath + body, SecretKey))`.
`OK-ACCESS-TIMESTAMP`	UTC timestamp.
`OK-ACCESS-PASSPHRASE`	Passphrase set when creating the API Key.

Write Operation Signing Model#

All write operations, including order placement, cancellation, modification, leverage adjustment, margin adjustment, position-mode switching, and account transfers, use EIP-712 Action signatures.

Request body structure:

json

{
  "action": {},
  "nonce": 1704067200000,
  "user": "0x...",
  "vaultAddress": "0x...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  },
  "expiresAfter": 1704067260000
}

Field	Type	Required	Description
`action`	Object	Yes	Business action object and the EIP-712 signing object. All business parameters are contained in `action`.
`nonce`	Long	Yes	Current timestamp in milliseconds, used for signing and replay protection.
`user`	String	No	Business-account address. When not explicitly provided, it is resolved according to the signing principal or endpoint rules.
`vaultAddress`	String	No	Sub-account address. Omit when operating on the master account; provide the sub-account address when operating on a sub-account.
`signature`	Object	Yes	ECDSA signature of the complete `action` by the Agent. `r` and `s` are hexadecimal strings, and `v` is `0` or `1`.
`expiresAfter`	Long	No	Action expiration time. Requests are rejected after this time. Required for `cancel-all-after` heartbeat requests.

Signing flow:

Construct the complete canonical action.
Generate nonce using the current timestamp in milliseconds.
Sign action with EIP-712 using the ECDSA private key of an authorized Agent.
Submit the signed request to the relevant endpoint with the OK-ACCESS-* headers.

The server does not construct or modify action on behalf of clients. Any field change after signing causes signature validation to fail.

Sub-account Queries#

The following read endpoints support the optional vaultAddress parameter:

Omit vaultAddress: Query master-account data.
Provide vaultAddress: Query the specified sub-account data.

The gateway verifies that the address belongs to the authenticated user.

Applicable endpoints:

text

/account/balance
/account/positions
/account/max-size
/account/leverage-info
/account/position-tiers
/account/bills
/trade/order
/trade/orders-pending
/trade/orders-history
/trade/fills

The following endpoints always operate at the master-account level and do not support vaultAddress:

text

/account/detail
/account/trade-fee

Rate Limit Overview#

Trade Endpoints

Rate-limit scope: per user.

Endpoint	Rate Limit
`POST /trade/noop`	50 RPS
`POST /trade/place-order`	50 RPS
`POST /trade/cancel-order`	50 RPS
`POST /trade/modify-order`	50 RPS
`POST /trade/cancel-all-after`	1 RPS
`GET /trade/transaction`	30 RPS
`GET /trade/order`	30 RPS
`GET /trade/orders-pending`	30 RPS
`GET /trade/orders-history`	20 RPS
`GET /trade/fills`	30 RPS

Account Endpoints

Rate-limit scope: per user.

Endpoint	Rate Limit
`POST /account/account-transfer`	10 RPS
`GET /account/balance`	10 RPS
`GET /account/positions`	10 RPS
`GET /account/max-size`	10 RPS
`GET /account/position-tiers`	5 RPS
`POST /account/set-leverage`	10 RPS
`POST /account/set-margin-mode`	10 RPS
`POST /account/adjust-isolated-margin`	10 RPS
`POST /account/set-position-mode`	5 RPS
`GET /account/leverage-info`	5 RPS
`GET /account/trade-fee`	3 RPS
`GET /account/bills`	5 RPS
`GET /account/detail`	3 RPS
`POST /account/create-sub-account`	3 RPS
`GET /account/limits`	10 RPS

Market Endpoints

Rate-limit scope: per IP.

Endpoint	Rate Limit
`GET /market/instruments`	10 RPS
`GET /market/tickers`	10 RPS
`GET /market/order-book`	10 RPS
`GET /market/candles`	20 RPS
`GET /market/mark-prices`	10 RPS
`GET /market/position-tiers`	10 RPS
`GET /market/funding-rate-history`	5 RPS
`GET /market/funding-rate`	10 RPS
`GET /market/open-interest`	10 RPS
`GET /market/price-limit`	10 RPS
`GET /market/index-tickers`	10 RPS
`GET /market/token-info`	10 RPS
`GET /market/security-fund`	5 RPS

Table of contents

Base Path

Environment

Identifier Conventions

Units

Response Format

Write Endpoint Authentication

Write Operation Signing Model

Sub-account Queries

Rate Limit Overview