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

Innhold

Base Path

Environment

Identifier Conventions

Response Format

Write Endpoint Authentication

Write Operation Signing Model

Sub-account Queries

Rate Limit Overview