Overview

Welcome to our V5 API documentation. Turkey provides REST and WebSocket APIs to suit your trading needs.

API Resources and Support

Tutorials

Learn how to trade with V5 API: Best practice to OKX’s v5 API
Learn python spot trading step by step: Python Spot Trading Tutorial
Learn python derivatives trading step by step: Python Derivatives Trading Tutorial

Python libraries

Use Python SDK for easier integration: Python SDK
Get access to our market maker python sample code Python market maker sample

Customer service

Get support in our Telegram group: https://t.me/OKXAPI
Subscribe to API related changes: https://t.me/OKExAPIChannel
Please take 1 minute to help us improve: V5 API Satisfaction Survey
If you have any questions, please consult online customer service

V5 API Key Creation

Please refer to my api page regarding V5 API Key creation.

Generating an API Key

Create an API Key on the website before signing any requests. After creating an APIKey, keep the following information safe:

APIKey
SecretKey
Passphrase

The system returns randomly-generated APIKeys and SecretKeys. You will need to provide the Passphrase to access the API. We store the salted hash of your Passphrase for authentication. We cannot recover the Passphrase if you have lost it. You will need to create a new set of APIKey.

There are three permissions below that can be associated with an API key. One or more permission can be assigned to any key.

Read : Can request and view account info such as bills and order history which need read permission
Trade : Can place and cancel orders, funding transfer, make settings which need write permission
Withdraw : Can make withdrawals

REST Authentication

Making Requests

All private REST requests must contain the following headers:

OK-ACCESS-KEY The API Key as a String.
OK-ACCESS-SIGN The Base64-encoded signature (see Signing Messages subsection for details).
OK-ACCESS-TIMESTAMP The UTC timestamp of your request .e.g : 2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE The passphrase you specified when creating the APIKey.

Request bodies should have content type application/json and be in valid JSON format.

Signature

Signing Messages

The OK-ACCESS-SIGN header is generated as follows:

Create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation).
Prepare the SecretKey.
Sign the prehash string with the SecretKey using the HMAC SHA256.
Encode the signature in the Base64 format.

Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))

The timestamp value is the same as the OK-ACCESS-TIMESTAMP header with millisecond ISO format, e.g. 2020-12-08T09:08:57.715Z.

The request method should be in UPPERCASE: e.g. GET and POST.

The requestPath is the path of requesting an endpoint.

Example: /api/v5/account/balance

The body refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET requests).

Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}

The SecretKey is generated when you create an APIKey.

Example: 22582BD0CFF14C41EDBF1AB98506286D

WebSocket

Overview

WebSocket is a new HTML5 protocol that achieves full-duplex data transmission between the client and server, allowing data to be transferred effectively in both directions. A connection between the client and server can be established with just one handshake. The server will then be able to push data to the client according to preset rules. Its advantages include:

The WebSocket request header size for data transmission between client and server is only 2 bytes.
Either the client or server can initiate data transmission.
There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.

Connect

Connection limit: 3 requests per second (based on IP)

When subscribing to a public channel, use the address of the public service. When subscribing to a private channel, use the address of the private service

Request limit:

The total number of 'subscribe'/'unsubscribe'/'login' requests per connection is limited to 480 times per hour.

Connection count limit

The limit will be set at 20 WebSocket connections per specific WebSocket channel per sub-account. Each WebSocket connection is identified by the unique connId.

The WebSocket channels subject to this limitation are as follows:

If users subscribe to the same channel through the same WebSocket connection through multiple arguments, for example, by using {"channel": "orders", "instType": "ANY"} and {"channel": "orders", "instType": "SWAP"}, it will be counted once only. If users subscribe to the listed channels (such as orders and accounts) using either the same or different connections, it will not affect the counting, as these are considered as two different channels. The system calculates the number of WebSocket connections per channel.

The platform will send the number of active connections to clients through the channel-conn-count event message to new channel subscriptions.

Connection count update

{
    "event":"channel-conn-count",
    "channel":"orders",
    "connCount": "2",
    "connId":"abcd1234"
}

When the limit is breached, generally the latest connection that sends the subscription request will be rejected. Client will receive the usual subscription acknowledgement followed by the channel-conn-count-error from the connection that the subscription has been terminated. In exceptional circumstances the platform may unsubscribe existing connections.

Connection limit error

{
    "event": "channel-conn-count-error",
    "channel": "orders",
    "connCount": "20",
    "connId":"a4d3ae55"
}

Order operations through WebSocket, including place, amend and cancel orders, are not impacted through this change.

Request Example

{
  "op": "login",
  "args": [
    {
      "apiKey": "985d5b66-57ce-40fb-b714-afc0b9787083",
      "passphrase": "123456",
      "timestamp": "1538054050",
      "sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="
    }
  ]
}

Parameter	Type	Required	Description
op	String	Yes	Operation `login`
args	Array	Yes	List of account to login
> apiKey	String	Yes	API Key
> passphrase	String	Yes	API Key password
> timestamp	String	Yes	Unix Epoch time, the unit is seconds
> sign	String	Yes	Signature string

Successful Response Example

{
  "event": "login",
  "code": "0",
  "msg": "",
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60009",
  "msg": "Login failed.",
  "connId": "a4d3ae55"
}

Parameter	Type	Required	Description
event	String	Yes	Operation `login` `error`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

apiKey: Unique identification for invoking API. Requires user to apply one manually.

passphrase: API Key password

timestamp: the Unix Epoch time, the unit is seconds, e.g. 1704876947

sign: signature string, the signature algorithm is as follows:

First concatenate timestamp, method, requestPath, strings, then use HMAC SHA256 method to encrypt the concatenated string with SecretKey, and then perform Base64 encoding.

secretKey: The security key generated when the user applies for APIKey, e.g. : 22582BD0CFF14C41EDBF1AB98506286D

Example of timestamp: const timestamp = '' + Date.now() / 1,000

Among sign example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp +'GET'+'/users/self/verify', secretKey))

method: always 'GET'.

requestPath : always '/users/self/verify'

Subscription Instructions

Request format description

{
  "op": "subscribe",
  "args": ["<SubscriptionTopic>"]
}

WebSocket channels are divided into two categories: public and private channels.

Public channels -- No authentication is required, include tickers channel, K-Line channel, limit price channel, order book channel, and mark price channel etc.

Private channels -- including account channel, order channel, and position channel, etc -- require log in.

Users can choose to subscribe to one or more channels, and the total length of multiple channels cannot exceed 64 KB.

Below is an example of subscription parameters. The requirement of subscription parameters for each channel is different. For details please refer to the specification of each channels.

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "tickers",
      "instId": "LTC-USD-200327"
    },
    {
      "channel": "candle1m",
      "instId": "LTC-USD-200327"
    }
  ]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name
> instType	String	No	Instrument type `SPOT` `MARGIN` `SWAP` `FUTURES` `OPTION` `ANY`
> instFamily	String	No	Instrument family Applicable to `FUTURES`/`SWAP`/`OPTION`
> instId	String	No	Instrument ID

Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "tickers",
    "instId": "LTC-USD-200327"
  },
  "connId": "a4d3ae55"
}

Return parameters

Parameter	Type	Required	Description
event	String	Yes	Event, `subscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instType	String	No	Instrument type `SPOT` `MARGIN` `SWAP` `FUTURES` `OPTION` `ANY`
> instFamily	String	No	Instrument family Applicable to `FUTURES`/`SWAP`/`OPTION`
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Unsubscribe

Unsubscribe from one or more channels.

Request format description

{
  "op": "unsubscribe",
  "args": ["< SubscriptionTopic> "]
}

Request Example

{
  "op": "unsubscribe",
  "args": [
    {
      "channel": "tickers",
      "instId": "LTC-USD-200327"
    },
    {
      "channel": "candle1m",
      "instId": "LTC-USD-200327"
    }
  ]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `unsubscribe`
args	Array	Yes	List of channels to unsubscribe from
> channel	String	Yes	Channel name
> instType	String	No	Instrument type `SPOT` `MARGIN` `SWAP` `FUTURES` `OPTION` `ANY`
> instFamily	String	No	Instrument family Applicable to `FUTURES`/`SWAP`/`OPTION`
> instId	String	No	Instrument ID

Response Example

{
  "event": "unsubscribe",
  "arg": {
    "channel": "tickers",
    "instId": "LTC-USD-200327"
  },
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event, `unsubscribe` `error`
arg	Object	No	Unsubscribed channel
> channel	String	Yes	Channel name
> instType	String	No	Instrument type `SPOT` `MARGIN` `SWAP` `FUTURES` `OPTION`
> instFamily	String	No	Instrument family Applicable to `FUTURES`/`SWAP`/`OPTION`
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error message

Account mode

To facilitate your trading experience, please set the appropriate account mode before starting trading.

In the trading account trading system, 4 account modes are supported: Spot mode, Spot and futures mode, Multi-currency margin mode, and Portfolio margin mode.

You need to set on the Web/App for the first set of every account mode.

Production Trading Services

The Production Trading URL:

REST: https://tr.okx.com
Public WebSocket: wss://ws.okx.com:8443/ws/v5/public
Private WebSocket: wss://ws.okx.com:8443/ws/v5/private
Business WebSocket: wss://ws.okx.com:8443/ws/v5/business

Transaction Timeouts

Orders may not be processed in time due to network delay or busy OKX servers. You can configure the expiry time of the request using expTime if you want the order request to be discarded after a specific time.

If expTime is specified in the requests for Place (multiple) orders or Amend (multiple) orders, the request will not be processed if the current system time of the server is after the expTime.

You should synchronize with our system time. Use Get system time to obtain the current system time.

REST API

Set the following parameters in the request header

Parameter	Type	Required	Description
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

The following endpoints are supported:

Request Example

curl -X 'POST' \
  'https://www.okx.com/api/v5/trade/order' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'OK-ACCESS-KEY: *****' \
  -H 'OK-ACCESS-SIGN: *****'' \
  -H 'OK-ACCESS-TIMESTAMP: *****'' \
  -H 'OK-ACCESS-PASSPHRASE: *****'' \
  -H 'expTime: 1597026383085' \   // request effective deadline
  -d '{
  "instId": "BTC-USDT",
  "tdMode": "cash",
  "side": "buy",
  "ordType": "limit",
  "px": "1000",
  "sz": "0.01"
}'

WebSocket

The following parameters are set in the request

Parameter	Type	Required	Description
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

The following endpoints are supported:

Request Example

{
    "id": "1512",
    "op": "order",
    "expTime":"1597026383085",  // request effective deadline
    "args": [{
        "side": "buy",
        "instId": "BTC-USDT",
        "tdMode": "isolated",
        "ordType": "market",
        "sz": "100"
    }]
}

Rate Limits

Our REST and WebSocket APIs use rate limits to protect our APIs against malicious usage so our trading platform can operate reliably and fairly.
When a request is rejected by our system due to rate limits, the system returns error code 50011 (Rate limit reached. Please refer to API documentation and throttle requests accordingly).
The rate limit is different for each endpoint. You can find the limit for each endpoint from the endpoint details. Rate limit definitions are detailed below:

WebSocket login and subscription rate limits are based on connection.
Public unauthenticated REST rate limits are based on IP address.
Private REST rate limits are based on User ID (sub-accounts have individual User IDs).
WebSocket order management rate limits are based on User ID (sub-accounts have individual User IDs).

For Trading-related APIs (place order, cancel order, and amend order) the following conditions apply:

Rate limits are shared across the REST and WebSocket channels.
Rate limits for placing orders, amending orders, and cancelling orders are independent from each other.
Rate limits are defined on the Instrument ID level (except Options)
Rate limits for Options are defined based on the Instrument Family level. Refer to the Get instruments endpoint to view Instrument Family information.
Rate limits for a multiple order endpoint and a single order endpoint are also independent, with the exception being when there is only one order sent to a multiple order endpoint, the order will be counted as a single order and adopt the single order rate limit.

Sub-account rate limit

At the sub-account level, we allow a maximum of 1000 order requests per 2 seconds. Only new order requests and amendment order requests will be counted towards this limit. The limit encompasses all requests from the endpoints below. For batch order requests consisting of multiple orders, each order will be counted individually. Error code 50061 is returned when the sub-account rate limit is exceeded. The existing rate limit rule per instrument ID remains unchanged and the existing rate limit and sub-account rate limit will operate in parallel. If clients require a higher rate limit, clients can trade via multiple sub-accounts.

Fill ratio based sub-account rate limit

This is only applicable to >= VIP5 customers.
As an incentive for more efficient trading, the exchange will offer a higher sub-account rate limit to clients with a high trade fill ratio.

The exchange calculates two ratios based on the transaction data from the past 7 days at 00:00 UTC.

Sub-account fill ratio: This ratio is determined by dividing (the trade volume in USDT of the sub-account) by (sum of (new and amendment request count per symbol * symbol multiplier) of the sub-account). Note that the master trading account itself is also considered as a sub-account in this context.
Master account aggregated fill ratio: This ratio is calculated by dividing (the trade volume in USDT on the master account level) by (the sum (new and amendment count per symbol * symbol multiplier] of all sub-accounts).

The symbol multiplier allows for fine-tuning the weight of each symbol. A smaller symbol multiplier (<1) is used for smaller pairs that require more updates per trading volume. All instruments have a default symbol multiplier, and some instruments will have overridden symbol multipliers.

InstType	Override rule	Overridden symbol multiplier	Default symbol multiplier
Perpetual Futures	Per instrument ID	`1` Instrument ID: BTC-USDT-SWAP BTC-USD-SWAP ETH-USDT-SWAP ETH-USD-SWAP	`0.2`
Expiry Futures	Per instrument Family	`0.3` Instrument Family: BTC-USDT BTC-USD ETH-USDT ETH-USD	`0.1`
Spot	Per instrument ID	`0.5` Instrument ID: BTC-USDT ETH-USDT	`0.1`
Options	Per instrument Family		`0.1`

The fill ratio computation excludes block trading, spread trading, MMP and fiat orders for order count; and excludes block trading, spread trading for trade volume. Only successful order requests (sCode=0) are considered.

At 08:00 UTC, the system will use the maximum value between the sub-account fill ratio and the master account aggregated fill ratio based on the data snapshot at 00:00 UTC to determine the sub-account rate limit based on the table below. For broker (non-disclosed) clients, the system considers the sub-account fill ratio only.

	Fill ratio[x<=ratio<y)	Sub-account rate limit per 2 seconds(new and amendment)
Tier 1	[0,1)	1,000
Tier 2	[1,2)	1,250
Tier 3	[2,3)	1,500
Tier 4	[3,5)	1,750
Tier 5	[5,10)	2,000
Tier 6	[10,20)	2,500
Tier 7	[20,50)	3,000
Tier 8	>= 50	10,000

If there is an improvement in the fill ratio and rate limit to be uplifted, the uplift will take effect immediately at 08:00 UTC. However, if the fill ratio decreases and the rate limit needs to be lowered, a one-day grace period will be granted, and the lowered rate limit will only be implemented on T+1 at 08:00 UTC. On T+1, if the fill ratio improves, the higher rate limit will be applied accordingly. In the event of client demotion to VIP4, their rate limit will be downgraded to Tier 1, accompanied by a one-day grace period.

If the 7-day trading volume of a sub-account is less than 1,000,000 USDT, the fill ratio of the master account will be applied to it.

For newly created sub-accounts, the Tier 1 rate limit will be applied at creation until T+1 8am UTC, at which the normal rules will be applied.

Block trading, spread trading, MMP and spot/margin orders are exempted from the sub-account rate limit.

The exchange offers GET / Account rate limit endpoint that provides ratio and rate limit data, which will be updated daily at 8am UTC. It will return the sub-account fill ratio, the master account aggregated fill ratio, current sub-account rate limit and sub-account rate limit on T+1 (applicable if the rate limit is going to be demoted).

The fill ratio and rate limit calculation example is shown below. Client has 3 accounts, symbol multiplier for BTC-USDT-SWAP = 1 and XRP-USDT = 0.1.

Account A (master account):
1. BTC-USDT-SWAP trade volume = 100 USDT, order count = 10;
2. XRP-USDT trade volume = 20 USDT, order count = 15;
3. Sub-account ratio = (100+20) / (10 * 1 + 15 * 0.1) = 10.4
Account B (sub-account):
1. BTC-USDT-SWAP trade volume = 200 USDT, order count = 100;
2. XRP-USDT trade volume = 20 USDT, order count = 30;
3. Sub-account ratio = (200+20) / (100 * 1 + 30 * 0.1) = 2.13
Account C (sub-account):
1. BTC-USDT-SWAP trade volume = 300 USDT, order count = 1000;
2. XRP-USDT trade volume = 20 USDT, order count = 45;
3. Sub-account ratio = (300+20) / (100 * 1 + 45 * 0.1) = 3.06
Master account aggregated fill ratio = (100+20+200+20+300+20) / (10 * 1 + 15 * 0.1 + 100 * 1 + 30 * 0.1 + 100 * 1 + 45 * 0.1) = 3.01
Rate limit of accounts
1. Account A = max(10.4, 3.01) = 10.4 -> 2500 order requests/2s
2. Account B = max(2.13, 3.01) = 3.01 -> 1750 order requests/2s
3. Account C = max(3.06, 3.01) = 3.06 -> 1750 order requests/2s

Best practices

If you require a higher request rate than our rate limit, you can set up different sub-accounts to batch request rate limits. We recommend this method for throttling or spacing out requests in order to maximize each accounts' rate limit and avoid disconnections or rejections.

Trading Account

The API endpoints of Account require authentication.

REST API

Get instruments

Retrieve available instruments info of current account.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID + InstrumentType

HTTP Request

GET /api/v5/account/instruments

Request Example

GET /api/v5/account/instruments?instType=SPOT

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1" # Production trading: 0, Demo trading: 1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

result = accountAPI.get_instruments(instType="SPOT")
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument type `SPOT`: Spot `MARGIN`: Margin `SWAP`: Perpetual Futures `FUTURES`: Expiry Futures `OPTION`: Option
uly	String	Conditional	Underlying Only applicable to `FUTURES`/`SWAP`/`OPTION`.If instType is `OPTION`, either `uly` or `instFamily` is required.
instFamily	String	Conditional	Instrument family Only applicable to `FUTURES`/`SWAP`/`OPTION`. If instType is `OPTION`, either `uly` or `instFamily` is required.
instId	String	No	Instrument ID

Response Example

{
    "code": "0",
    "data": [
        {
            "baseCcy": "BTC",
            "ctMult": "",
            "ctType": "",
            "ctVal": "",
            "ctValCcy": "",
            "expTime": "",
            "instFamily": "",
            "instId": "BTC-EUR",
            "instType": "SPOT",
            "lever": "",
            "listTime": "1704876947000",
            "lotSz": "0.00000001",
            "maxIcebergSz": "9999999999.0000000000000000",
            "maxLmtAmt": "1000000",
            "maxLmtSz": "9999999999",
            "maxMktAmt": "1000000",
            "maxMktSz": "1000000",
            "maxStopSz": "1000000",
            "maxTriggerSz": "9999999999.0000000000000000",
            "maxTwapSz": "9999999999.0000000000000000",
            "minSz": "0.00001",
            "optType": "",
            "quoteCcy": "EUR",
            "settleCcy": "",
            "state": "live",
            "ruleType": "normal",
            "stk": "",
            "tickSz": "1",
            "uly": ""
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID, e.g. `BTC-USD-SWAP`
uly	String	Underlying, e.g. `BTC-USD` Only applicable to `MARGIN/FUTURES`/`SWAP`/`OPTION`
instFamily	String	Instrument family, e.g. `BTC-USD` Only applicable to `MARGIN/FUTURES`/`SWAP`/`OPTION`
baseCcy	String	Base currency, e.g. `BTC` in`BTC-USDT` Only applicable to `SPOT`/`MARGIN`
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT` Only applicable to `SPOT`/`MARGIN`
settleCcy	String	Settlement and margin currency, e.g. `BTC` Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctVal	String	Contract value Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctMult	String	Contract multiplier Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctValCcy	String	Contract value currency Only applicable to `FUTURES`/`SWAP`/`OPTION`
optType	String	Option type, `C`: Call `P`: put Only applicable to `OPTION`
stk	String	Strike price Only applicable to `OPTION`
listTime	String	Listing time, Unix timestamp format in milliseconds, e.g. `1597026383085`
expTime	String	Expiry time Applicable to `SPOT`/`MARGIN`/`FUTURES`/`SWAP`/`OPTION`. For `FUTURES`/`OPTION`, it is natural delivery/exercise time. It is the instrument offline time when there is `SPOT/MARGIN/FUTURES/SWAP/` manual offline. Update once change.
lever	String	Max Leverage, Not applicable to `SPOT`, `OPTION`
tickSz	String	Tick size, e.g. `0.0001` For Option, it is minimum tickSz among tick band, please use "Get option tick bands" if you want get option tickBands.
lotSz	String	Lot size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
minSz	String	Minimum order size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
ctType	String	Contract type `linear`: linear contract `inverse`: inverse contract Only applicable to `FUTURES`/`SWAP`
state	String	Instrument status `live` `suspend` `preopen`. e.g. There will be `preopen` before the Futures and Options new contracts state is live. `test`: Test pairs, can't be traded
ruleType	String	Trading rule types `normal`: normal trading `pre_market`: pre-market trading
maxLmtSz	String	The maximum order quantity of a single limit order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxMktSz	String	The maximum order quantity of a single market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.
maxLmtAmt	String	Max USD amount for a single limit order
maxMktAmt	String	Max USD amount for a single market order Only applicable to `SPOT`/`MARGIN`
maxTwapSz	String	The maximum order quantity of a single TWAP order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`. The minimum order quantity of a single TWAP order is minSz*2
maxIcebergSz	String	The maximum order quantity of a single iceBerg order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxTriggerSz	String	The maximum order quantity of a single trigger order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxStopSz	String	The maximum order quantity of a single stop market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.

Get balance

Retrieve a list of assets (with non-zero balance), remaining balance, and available amount in the trading account.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/account/balance

Request Example

# Get the balance of all assets in the account
GET /api/v5/account/balance

# Get the balance of BTC and ETH assets in the account
GET /api/v5/account/balance?ccy=BTC,ETH

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get account balance
result = accountAPI.get_account_balance()
print(result)

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Response Example

{
    "code": "0",
    "data": [
        {
            "adjEq": "55415.624719833286",
            "borrowFroz": "0",
            "details": [
                {
                    "availBal": "4834.317093622894",
                    "availEq": "4834.3170936228935",
                    "borrowFroz": "0",
                    "cashBal": "4850.435693622894",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "4991.542013297616",
                    "eq": "4992.890093622894",
                    "eqUsd": "4991.542013297616",
                    "fixedBal": "0",
                    "frozenBal": "158.573",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl": "0",
                    "liab": "0",
                    "maxLoan": "0",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "spotInUseAmt": "",
                    "spotIsoBal": "0",
                    "stgyEq": "150",
                    "twap": "0",
                    "uTime": "1705449605015",
                    "upl": "-7.545600000000006",
                    "uplLiab": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                }
            ],
            "imr": "8.57068529",
            "isoEq": "0",
            "mgnRatio": "143682.59776662575",
            "mmr": "0.3428274116",
            "notionalUsd": "85.7068529",
            "ordFroz": "0",
            "totalEq": "55837.43556134779",
            "uTime": "1705474164160",
            "upl": "-7.543562688000006"
        }
    ],
    "msg": ""
}

Response Parameters

Parameters	Types	Description
uTime	String	Update time of account information, millisecond format of Unix timestamp, e.g. `1597026383085`
totalEq	String	The total amount of equity in `USD`
isoEq	String	Isolated margin equity in `USD` Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
adjEq	String	Adjusted / Effective equity in `USD` The net fiat value of the assets in the account that can provide margins for spot, expiry futures, perpetual futures and options under the cross-margin mode. In multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation. Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks. Applicable to `Multi-currency margin` and `Portfolio margin`
ordFroz	String	Cross margin frozen for pending orders in `USD` Only applicable to `Multi-currency margin`
imr	String	Initial margin requirement in `USD` The sum of initial margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Multi-currency margin`/`Portfolio margin`
mmr	String	Maintenance margin requirement in `USD` The sum of maintenance margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Multi-currency margin`/`Portfolio margin`
borrowFroz	String	Potential borrowing IMR of the account in `USD` Only applicable to `Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
mgnRatio	String	Margin ratio in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
notionalUsd	String	Notional value of positions in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
upl	String	Cross-margin info of unrealized profit and loss at the account level in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
details	Array	Detailed asset information in all currencies
> ccy	String	Currency
> eq	String	Equity of currency
> cashBal	String	Cash balance
> uTime	String	Update time of currency balance information, Unix timestamp format in milliseconds, e.g. `1597026383085`
> isoEq	String	Isolated margin equity of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> availEq	String	Available equity of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> disEq	String	Discount equity of currency in `USD`.
> fixedBal	String	Frozen balance for `Dip Sniper` and `Peak Sniper`
> availBal	String	Available balance of currency
> frozenBal	String	Frozen balance of currency
> ordFrozen	String	Margin frozen for open orders Applicable to `Spot mode`/`Spot and futures mode`/`Multi-currency margin`
> liab	String	Liabilities of currency It is a positive value, e.g. `21625.64` Applicable to `Multi-currency margin`/`Portfolio margin`
> upl	String	The sum of the unrealized profit & loss of all margin and derivatives positions of currency. Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> uplLiab	String	Liabilities due to Unrealized loss of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> crossLiab	String	Cross liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> isoLiab	String	Isolated liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> mgnRatio	String	Cross margin ratio of currency The index for measuring the risk of a certain asset in the account. Applicable to `Spot and futures mode` and when there is cross position
> imr	String	Cross initial margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
> mmr	String	Cross maintenance margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
> interest	String	Accrued interest of currency It is a positive value, e.g. `9.01` Applicable to `Multi-currency margin`/`Portfolio margin`
> twap	String	Risk indicator of auto liability repayment Divided into multiple levels from 0 to 5, the larger the number, the more likely the auto repayment will be triggered. Applicable to `Multi-currency margin`/`Portfolio margin`
> maxLoan	String	Max loan of currency Applicable to `cross` of `Multi-currency margin`/`Portfolio margin`
> eqUsd	String	Equity in `USD` of currency
> borrowFroz	String	Potential borrowing IMR of currency in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
> notionalLever	String	Leverage of currency Applicable to `Spot and futures mode`
> stgyEq	String	Strategy equity
> isoUpl	String	Isolated unrealized profit and loss of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> spotInUseAmt	String	Spot in use amount Applicable to `Portfolio margin`
> spotIsoBal	String	Spot isolated balance Applicable to copy trading Applicable to `Spot mode`/`Spot and futures mode`
> spotBal	String	Spot balance. The unit is currency, e.g. BTC. Clicking knows more
> openAvgPx	Array	Spot average cost price. The unit is USD. Clicking knows more
> accAvgPx	Array	Spot accumulated cost price. The unit is USD. Clicking knows more
> spotUpl	String	Spot unrealized profit and loss. The unit is USD. Clicking knows more
> spotUplRatio	String	Spot unrealized profit and loss ratio. Clicking knows more
> totalPnl	String	Spot accumulated profit and loss. The unit is USD. Clicking knows more
> totalPnlRatio	String	Spot accumulated profit and loss ratio. Clicking knows more

Distribution of applicable fields under each account level are as follows:

Parameters	Spot mode	Spot and futures mode	Multi-currency margin mode	Portfolio margin mode
uTime	Yes	Yes	Yes	Yes
totalEq	Yes	Yes	Yes	Yes
isoEq		Yes	Yes	Yes
adjEq			Yes	Yes
ordFroz			Yes	Yes
imr			Yes	Yes
mmr			Yes	Yes
mgnRatio			Yes	Yes
notionalUsd			Yes	Yes
upl			Yes	Yes
details			Yes	Yes
> ccy	Yes	Yes	Yes	Yes
> eq	Yes	Yes	Yes	Yes
> cashBal	Yes	Yes	Yes	Yes
> uTime	Yes	Yes	Yes	Yes
> isoEq		Yes	Yes	Yes
> availEq		Yes	Yes	Yes
> disEq	Yes	Yes	Yes	Yes
> availBal	Yes	Yes	Yes	Yes
> frozenBal	Yes	Yes	Yes	Yes
> ordFrozen	Yes	Yes	Yes	Yes
> liab			Yes	Yes
> upl		Yes	Yes	Yes
> uplLiab			Yes	Yes
> crossLiab			Yes	Yes
> isoLiab			Yes	Yes
> mgnRatio		Yes
> interest			Yes	Yes
> twap			Yes	Yes
> maxLoan			Yes	Yes
> eqUsd	Yes	Yes	Yes	Yes
> notionalLever		Yes
> stgyEq	Yes	Yes	Yes	Yes
> isoUpl		Yes	Yes	Yes
> spotInUseAmt				Yes
> spotIsoBal	Yes	Yes
> imr		Yes
> mmr		Yes
> spotBal	Yes	Yes	Yes	Yes
> openAvgPx	Yes	Yes	Yes	Yes
> accAvgPx	Yes	Yes	Yes	Yes
> spotUpl	Yes	Yes	Yes	Yes
> spotUplRatio	Yes	Yes	Yes	Yes
> totalPnl	Yes	Yes	Yes	Yes
> totalPnlRatio	Yes	Yes	Yes	Yes

Get bills details (last 7 days)

Retrieve the bills of the account. The bill refers to all transaction records that result in changing the balance of an account. Pagination is supported, and the response is sorted with the most recent first. This endpoint can retrieve data from the last 7 days.

Rate Limit: 5 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/bills

Request Example

GET /api/v5/account/bills

GET /api/v5/account/bills?instType=SPOT

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get bills details (last 7 days)
result = accountAPI.get_account_bills()
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument type `SPOT`
ccy	String	No	Bill currency
type	String	No	Bill type `1`: Transfer `2`: Trade
subType	String	No	Bill subtype `1`: Buy `2`: Sell `11`: Transfer in `12`: Transfer out
after	String	No	Pagination of data to return records earlier than the requested bill ID.
before	String	No	Pagination of data to return records newer than the requested bill ID.
begin	String	No	Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "USDT",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillFwdPx": "",
        "fillIdxPx": "27104.1",
        "fillMarkPx": "",
        "fillMarkVol": "",
        "fillPxUsd": "",
        "fillPxVol": "",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "interest": "0",
        "mgnMode": "isolated",
        "notes": "",
        "ordId": "623950854525124608",
        "pnl": "0",
        "posBal": "0",
        "posBalChg": "0",
        "px": "27105.9",
        "subType": "1",
        "sz": "0.021955779",
        "tag": "",
        "to": "",
        "tradeId": "586760148",
        "ts": "1695033476167",
        "type": "2"
    }]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
billId	String	Bill ID
type	String	Bill type
subType	String	Bill subtype
ts	String	The time when the balance complete update, Unix timestamp format in milliseconds, e.g.`1597026383085`
balChg	String	Change in balance amount at the account level
posBalChg	String	Change in balance amount at the position level
bal	String	Balance at the account level
posBal	String	Balance at the position level
sz	String	Quantity
px	String	Price which related to subType Trade filled price for `1`: Buy `2`: Sell
ccy	String	Account balance currency
pnl	String	Profit and loss
fee	String	Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate.
mgnMode	String	Margin mode `isolated` `cross` When bills are not generated by position changes, the field returns ""
instId	String	Instrument ID, e.g. `BTC-USDT`
ordId	String	Order ID
execType	String	Liquidity taker or maker `T`: taker `M`: maker
from	String	The remitting account `6`: Funding account `18`: Trading account Only applicable to `transfer`. When bill type is not `transfer`, the field returns "".
to	String	The beneficiary account `6`: Funding account `18`: Trading account Only applicable to `transfer`. When bill type is not `transfer`, the field returns "".
notes	String	Notes
interest	String	Interest
tag	String	Order tag
fillTime	String	Last filled time
tradeId	String	Last traded ID
clOrdId	String	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
fillIdxPx	String	Index price at the moment of trade execution For cross currency spot pairs, it returns baseCcy-USDT index price. For example, for LTC-ETH, this field returns the index price of LTC-USDT.
fillMarkPx	String	Mark price when filled Applicable to FUTURES/SWAP/OPTIONS, return "" for other instrument types
fillPxVol	String	Implied volatility when filled Only applicable to options; return "" for other instrument types
fillPxUsd	String	Options price when filled, in the unit of USD Only applicable to options; return "" for other instrument types
fillMarkVol	String	Mark volatility when filled Only applicable to options; return "" for other instrument types
fillFwdPx	String	Forward price when filled Only applicable to options; return "" for other instrument types

Get bills details (last 3 months)

Retrieve the account’s bills. The bill refers to all transaction records that result in changing the balance of an account. Pagination is supported, and the response is sorted with most recent first. This endpoint can retrieve data from the last 3 months.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/bills-archive

Request Example

GET /api/v5/account/bills-archive

GET /api/v5/account/bills-archive?instType=SPOT

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get bills details (last 3 months)
result = accountAPI.get_account_bills_archive()
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument type `SPOT`
ccy	String	No	Bill currency
type	String	No	Bill type `1`: Transfer `2`: Trade `6`: Margin transfer
subType	String	No	Bill subtype `1`: Buy `2`: Sell `11`: Transfer in `12`: Transfer out `236`: Easy convert in `237`: Easy convert out
after	String	No	Pagination of data to return records earlier than the requested bill ID.
before	String	No	Pagination of data to return records newer than the requested bill ID.
begin	String	No	Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "USDT",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillFwdPx": "",
        "fillIdxPx": "27104.1",
        "fillMarkPx": "",
        "fillMarkVol": "",
        "fillPxUsd": "",
        "fillPxVol": "",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "interest": "0",
        "mgnMode": "isolated",
        "notes": "",
        "ordId": "623950854525124608",
        "pnl": "0",
        "posBal": "0",
        "posBalChg": "0",
        "px": "27105.9",
        "subType": "1",
        "sz": "0.021955779",
        "tag": "",
        "to": "",
        "tradeId": "586760148",
        "ts": "1695033476167",
        "type": "2"
    }]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
billId	String	Bill ID
type	String	Bill type
subType	String	Bill subtype
ts	String	The time when the balance complete update, Unix timestamp format in milliseconds, e.g.`1597026383085`
balChg	String	Change in balance amount at the account level
posBalChg	String	Change in balance amount at the position level
bal	String	Balance at the account level
posBal	String	Balance at the position level
sz	String	Quantity
px	String	Price which related to subType Trade filled price for `1`: Buy `2`: Sell
ccy	String	Account balance currency
pnl	String	Profit and loss
fee	String	Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate.
mgnMode	String	Margin mode `isolated` `cross` When bills are not generated by position changes, the field returns ""
instId	String	Instrument ID, e.g. `BTC-USDT`
ordId	String	Order ID When bill type is not `trade`, the field returns ""
execType	String	Liquidity taker or maker `T`: taker `M`: maker
from	String	The remitting account `6`: Funding account `18`: Trading account Only applicable to `transfer`. When bill type is not `transfer`, the field returns "".
to	String	The beneficiary account `6`: Funding account `18`: Trading account Only applicable to `transfer`. When bill type is not `transfer`, the field returns "".
notes	String	Notes
interest	String	Interest
tag	String	Order tag
fillTime	String	Last filled time
tradeId	String	Last traded ID
clOrdId	String	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
fillIdxPx	String	Index price at the moment of trade execution For cross currency spot pairs, it returns baseCcy-USDT index price. For example, for LTC-ETH, this field returns the index price of LTC-USDT.
fillMarkPx	String	Mark price when filled Applicable to FUTURES/SWAP/OPTIONS, return "" for other instrument types
fillPxVol	String	Implied volatility when filled Only applicable to options; return "" for other instrument types
fillPxUsd	String	Options price when filled, in the unit of USD Only applicable to options; return "" for other instrument types
fillMarkVol	String	Mark volatility when filled Only applicable to options; return "" for other instrument types
fillFwdPx	String	Forward price when filled Only applicable to options; return "" for other instrument types

Get account configuration

Retrieve current account configuration.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/config

Request Example

GET /api/v5/account/config

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve current account configuration
result = accountAPI.get_account_config()
print(result)

Request Parameters

none

Response Example

{
    "code": "0",
    "data": [
        {
            "acctLv": "2",
            "acctStpMode": "cancel_maker",
            "autoLoan": false,
            "ctIsoMode": "automatic",
            "discountType": "1",
            "enableSpotBorrow": false,
            "greeksType": "PA",
            "ip": "",
            "kycLv": "3",
            "label": "v5 test",
            "level": "Lv1",
            "levelTmp": "",
            "liquidationGear": "-1",
            "mainUid": "44705892343619584",
            "mgnIsoMode": "automatic",
            "opAuth": "1",
            "perm": "read_only,withdraw,trade",
            "posMode": "long_short_mode",
            "roleType": "0",
            "spotBorrowAutoRepay": false,
            "spotOffsetType": "",
            "spotRoleType": "0",
            "spotTraderInsts": [],
            "traderInsts": [],
            "uid": "44705892343619584"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
uid	String	Account ID of current request.
mainUid	String	Main Account ID of current request. The current request account is main account if uid = mainUid. The current request account is sub-account if uid != mainUid.
acctLv	String	Account mode `1`: Spot mode `2`: Spot and futures mode `3`: Multi-currency margin `4`: Portfolio margin
acctStpMode	String	Account self-trade prevention mode `cancel_maker` `cancel_taker` `cancel_both` Users can log in to the webpage through the master account to modify this configuration
posMode	String	Position mode `long_short_mode`: long/short, only applicable to `FUTURES`/`SWAP` `net_mode`: net
autoLoan	Boolean	Whether to borrow coins automatically `true`: borrow coins automatically `false`: not borrow coins automatically
greeksType	String	Current display type of Greeks `PA`: Greeks in coins `BS`: Black-Scholes Greeks in dollars
level	String	The user level of the current real trading volume on the platform, e.g `Lv1`
levelTmp	String	Temporary experience user level of special users, e.g `Lv3`
ctIsoMode	String	Contract isolated margin trading settings `automatic`: Auto transfers `autonomy`: Manual transfers
mgnIsoMode	String	Margin isolated margin trading settings `automatic`: Auto transfers `quick_margin`: Quick Margin Mode (For new accounts, including subaccounts, some defaults will be `automatic`, and others will be `quick_margin`)
spotOffsetType	String	Risk offset type `1`: Spot-Derivatives(USDT) to be offsetted `2`: Spot-Derivatives(Coin) to be offsetted `3`: Only derivatives to be offsetted Only applicable to `Portfolio margin`
roleType	String	Role type `0`: General user `1`: Leading trader `2`: Copy trader
traderInsts	Array	Leading trade instruments, only applicable to Leading trader
spotRoleType	String	SPOT copy trading role type. `0`: General user；`1`: Leading trader；`2`: Copy trader
spotTraderInsts	String	Spot lead trading instruments, only applicable to lead trader
opAuth	String	Whether the optional trading was activated `0`: not activate `1`: activated
kycLv	String	Main account KYC level `0`: No verification `1`: level 1 completed `2`: level 2 completed `3`: level 3 completed If the request originates from a subaccount, kycLv is the KYC level of the main account. If the request originates from the main account, kycLv is the KYC level of the current account.
label	String	API key note of current request API key. No more than 50 letters (case sensitive) or numbers, which can be pure letters or pure numbers.
ip	String	IP addresses that linked with current API key, separate with commas if more than one, e.g. `117.37.203.58,117.37.203.57`. It is an empty string "" if there is no IP bonded.
perm	String	The permission of the current requesting API key or Access token `read_only`: Read `trade`: Trade `withdraw`: Withdraw
discountType	String	Discount rule type for current account `0`: Original discount rate rules, the default value `1`: New discount rules After new discount rate rules are effective completely, this parameter will be removed from the endpoint. Advice you to prepare in advance.
liquidationGear	String	The margin ratio level of liquidation alert `3` means that you will get hourly liquidation alerts on app and channel "Position risk warning" when your margin level drops to or below 300% `0` means that there is not alert
enableSpotBorrow	Boolean	Whether borrow is allowed or not in `Spot mode` `true`: Enabled `false`: Disabled
spotBorrowAutoRepay	Boolean	Whether auto-repay is allowed or not in `Spot mode` `true`: Enabled `false`: Disabled

Get maximum order quantity

The maximum quantity to buy or sell. It corresponds to the "sz" from placement.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/max-size

Request Example

GET /api/v5/account/max-size?instId=BTC-USDT&tdMode=cash

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get maximum buy/sell amount or open amount
result = accountAPI.get_max_order_size(
    instId="BTC-USDT",
    tdMode="cash"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Single instrument or multiple instruments (no more than 5) in the smae instrument type separated with comma, e.g. `BTC-USDT,ETH-USDT`
tdMode	String	Yes	Trade mode `cash`
px	String	No	Price The parameter will be ignored when multiple instruments are specified.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "instId": "BTC-USDT",
        "maxBuy": "0.0500695098559788",
        "maxSell": "64.4798671570072269"
  }]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
ccy	String	Currency used for margin
maxBuy	String	`SPOT`: The maximum quantity in base currency that you can buy
maxSell	String	`SPOT`: The maximum quantity in quote currency that you can sell

Get maximum available balance/equity

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/max-avail-size

Request Example

# Query maximum available transaction amount for SPOT BTC-USDT
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cash

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get maximum available transaction amount for SPOT BTC-USDT
result = accountAPI.get_max_avail_size(
    instId="BTC-USDT",
    tdMode="cash"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Single instrument or multiple instruments (no more than 5) separated with comma, e.g. `BTC-USDT,ETH-USDT`
tdMode	String	Yes	Trade mode `cash`

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT",
      "availBuy": "100",
      "availSell": "1"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
availBuy	String	Amount available to buy
availSell	String	Amount available to sell

Get fee rates

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/trade-fee

Request Example

# Query trade fee rate of SPOT BTC-USDT
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT

import okx.Account as Account

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading:0 , demo trading:1

accountAPI = Account.AccountAPI(apikey, secretkey, passphrase, False, flag)

# Get trading fee rates of current account
result = accountAPI.get_fee_rates(
    instType="SPOT",
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT` Applicable to `SPOT`

Response Example

{
  "code": "0",
  "msg": "",
  "data": [{
    "category": "1", //Deprecated
    "delivery": "",
    "exercise": "",
    "instType": "SPOT",
    "level": "lv1",
    "maker": "-0.0008",
    "makerU": "",
    "makerUSDC": "",
    "taker": "-0.001",
    "takerU": "",
    "takerUSDC": "",
    "ts": "1608623351857",
    "fiat": []
   }
  ]
}

Response Parameters

Parameter	Type	Description
level	String	Fee rate Level
taker	String	For `SPOT`, it is taker fee rate of the USDT trading pairs.
maker	String	For `SPOT`, it is maker fee rate of the USDT trading pairs.
takerU	String	Taker fee rate of USDT-margined contracts, only applicable to `FUTURES`/`SWAP`
makerU	String	Maker fee rate of USDT-margined contracts, only applicable to `FUTURES`/`SWAP`
delivery	String	Delivery fee rate
exercise	String	Fee rate for exercising the option
instType	String	Instrument type
takerUSDC	String	For `SPOT`, it is taker fee rate of the USDⓈ&Crypto trading pairs.
makerUSDC	String	For `SPOT`, it is maker fee rate of the USDⓈ&Crypto trading pairs.
ts	String	Data return time, Unix timestamp format in milliseconds, e.g. `1597026383085`
category	String	Currency category. Note: this parameter is already deprecated
fiat	Array	Details of fiat fee rate
> ccy	String	Fiat currency.
> taker	String	Taker fee rate
> maker	String	Maker fee rate

WebSocket

Account channel

Retrieve account information. Data will be pushed when triggered by events such as placing order, canceling order, transaction execution, etc. It will also be pushed in regular interval according to subscription granularity.

Concurrent connection to this channel will be restricted by the following rules: WebSocket connection count limit.

URL Path

/ws/v5/private (required login)

Request Example : single

{
  "op": "subscribe",
  "args": [
    {
      "channel": "account",
      "ccy": "BTC"
    }
  ]
}

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "account",
      "extraParams": "
        {
          \"updateInterval\": \"0\"
        }
      "
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `account`
> ccy	String	No	Currency
> extraParams	String	No	Additional configuration
>> updateInterval	int	No	`0`: only push due to account events The data will be pushed both by events and regularly if this field is omitted or set to other values than 0. The following format should be strictly obeyed when using this field. "extraParams": " { \"updateInterval\": \"0\" } "

Successful Response Example : single

{
  "event": "subscribe",
  "arg": {
    "channel": "account",
    "ccy": "BTC"
  },
  "connId": "a4d3ae55"
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "account"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"account\", \"ccy\" : \"BTC\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Operation `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name `account`
> ccy	String	No	Currency
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "account",
        "uid": "44*********584"
    },
    "data": [{
        "adjEq": "55444.12216906034",
        "borrowFroz": "0",
        "details": [{
            "availBal": "4734.371190691436",
            "availEq": "4734.371190691435",
            "borrowFroz": "0",
            "cashBal": "4750.426970691436",
            "ccy": "USDT",
            "coinUsdPrice": "0.99927",
            "crossLiab": "0",
            "disEq": "4889.379316336831",
            "eq": "4892.951170691435",
            "eqUsd": "4889.379316336831",
            "smtSyncEq": "0",
            "fixedBal": "0",
            "frozenBal": "158.57998",
            "imr": "",
            "interest": "0",
            "isoEq": "0",
            "isoLiab": "0",
            "isoUpl": "0",
            "liab": "0",
            "maxLoan": "0",
            "mgnRatio": "",
            "mmr": "",
            "notionalLever": "",
            "ordFrozen": "0",
            "rewardBal": "0",
            "spotInUseAmt": "",
            "clSpotInUseAmt": "",
            "maxSpotInUseAmt": "",          
            "spotIsoBal": "0",
            "stgyEq": "150",
            "twap": "0",
            "uTime": "1705564213903",
            "upl": "-7.475800000000003",
            "uplLiab": "0",
            "spotBal": "",
            "openAvgPx": "",
            "accAvgPx": "",
            "spotUpl": "",
            "spotUplRatio": "",
            "totalPnl": "",
            "totalPnlRatio": ""
        }],
        "imr": "8.5737166146",
        "isoEq": "0",
        "mgnRatio": "143705.65988369548",
        "mmr": "0.342948664584",
        "notionalUsd": "85.737166146",
        "ordFroz": "0",
        "totalEq": "55868.06403501676",
        "uTime": "1705564223311",
        "upl": "-7.470342666000003"
    }]
}

Push data parameters

Parameters	Types	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> uid	String	User Identifier
data	Array	Subscribed data
> uTime	String	The latest time to get account information, millisecond format of Unix timestamp, e.g. `1597026383085`
> totalEq	String	The total amount of equity in `USD`
> isoEq	String	Isolated margin equity in `USD` Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> adjEq	String	Adjusted / Effective equity in `USD` The net fiat value of the assets in the account that can provide margins for spot, expiry futures, perpetual futures and options under the cross-margin mode. In multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation. Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
> ordFroz	String	Margin frozen for pending cross orders in `USD` Only applicable to `Spot mode`/`Multi-currency margin`
> imr	String	Initial margin requirement in `USD` The sum of initial margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
> mmr	String	Maintenance margin requirement in `USD` The sum of maintenance margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
> borrowFroz	String	Potential borrowing IMR of the account in `USD` Only applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
> mgnRatio	String	Margin ratio in `USD`. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
> notionalUsd	String	Notional value of positions in `USD` Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
> upl	String	Cross-margin info of unrealized profit and loss at the account level in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
> details	Array	Detailed asset information in all currencies
>> ccy	String	Currency
>> eq	String	Equity of currency
>> cashBal	String	Cash Balance
>> uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
>> isoEq	String	Isolated margin equity of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
>> availEq	String	Available equity of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
>> disEq	String	Discount equity of currency in `USD`
>> fixedBal	String	Frozen balance for `Dip Sniper` and `Peak Sniper`
>> availBal	String	Available balance of currency
>> frozenBal	String	Frozen balance of currency
>> ordFrozen	String	Margin frozen for open orders Applicable to `Spot mode`/`Spot and futures mode`/`Multi-currency margin`
>> liab	String	Liabilities of currency It is a positive value, e.g. `21625.64`. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
>> upl	String	The sum of the unrealized profit & loss of all margin and derivatives positions of currency. Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
>> uplLiab	String	Liabilities due to Unrealized loss of currency Applicable to `Multi-currency margin`/`Portfolio margin`
>> crossLiab	String	Cross Liabilities of currency Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
>> isoLiab	String	Isolated Liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
>> rewardBal	String	Trial fund balance
>> mgnRatio	String	Cross margin ratio of currency The index for measuring the risk of a certain asset in the account. Applicable to `Spot and futures mode` and when there is cross position
>> imr	String	Cross initial margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
>> mmr	String	Cross maintenance margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
>> interest	String	Interest of currency It is a positive value, e.g."9.01". Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
>> twap	String	System is forced repayment(TWAP) indicator Divided into multiple levels from 0 to 5, the larger the number, the more likely the auto repayment will be triggered. Applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`
>> maxLoan	String	Max loan of currency Applicable to `cross` of `Spot mode`/`Multi-currency margin`/`Portfolio margin`
>> eqUsd	String	Equity `USD` of currency
>> borrowFroz	String	Potential borrowing IMR of currency in `USD` Only applicable to `Spot mode`/`Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
>> notionalLever	String	Leverage of currency Applicable to `Spot and futures mode`
>> coinUsdPrice	String	Price index `USD` of currency
>> stgyEq	String	strategy equity
>> isoUpl	String	Isolated unrealized profit and loss of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
>> spotInUseAmt	String	Spot in use amount Applicable to `Portfolio margin`
>> clSpotInUseAmt	String	User-defined spot risk offset amount Applicable to `Portfolio margin`
>> maxSpotInUseAmt	String	Max possible spot risk offset amount Applicable to `Portfolio margin`
>> smtSyncEq	String	Smark sync equity The default is "0", only applicable to copy trader

Initial snapshot: Only currencies with non-zero balance will be pushed. Definition of non-zero balance: any value of eq, availEq, availBql parameters is not 0. If the data is too large to be sent in a single push message, it will be split into multiple messages.

Data pushed in regular interval: Only currencies with non-zero balance will be pushed. Definition of non-zero balance: any value of eq, availEq, availBql parameters is not 0.

For example, when subscribing to account channel without specifying ccy and there are 5 currencies are with non-zero balance, all 5 currencies data will be pushed in initial snapshot and in regular interval. Subsequently when there is change in balance or equity of an token, only the incremental data of that currency will be pushed triggered by this change.

Order Book Trading

Trade

All Trade API endpoints require authentication.

POST / Place order

You can place an order only if you have sufficient funds.

Rate Limit: 60 requests per 2 seconds

Rate limit rule : UserID + Instrument ID

HTTP Request

POST /api/v5/trade/order

Request Example

 place order for SPOT
 POST /api/v5/trade/order
 body
 {
    "instId":"BTC-USDT",
    "tdMode":"cash",
    "clOrdId":"b15",
    "side":"buy",
    "ordType":"limit",
    "px":"2.15",
    "sz":"2"
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Spot mode, limit order
result = tradeAPI.place_order(
    instId="BTC-USDT",
    tdMode="cash",
    clOrdId="b15",
    side="buy",
    ordType="limit",
    px="2.15",
    sz="2"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
tdMode	String	Yes	Trade mode `cash`
clOrdId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
side	String	Yes	Order side `buy` `sell`
ordType	String	Yes	Order type `market`: Market order `limit`: Limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
sz	String	Yes	Quantity to buy or sell
px	String	Conditional	Order price. Only applicable to `limit`,`post_only`,`fok`,`ioc`order.
tgtCcy	String	No	Whether the target currency uses the quote or base currency. `base_ccy`: Base currency `quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
banAmend	Boolean	No	Whether to disallow the system from amending the size of the SPOT Market Order. Valid options: `true` or `false`. The default value is `false`. If `true`, system will not amend and reject the market order if user does not have sufficient funds. Only applicable to SPOT Market Orders
stpId	String	No	Self trade prevention ID. Orders from the same master account with the same ID will be prevented from self trade. Numerical integers defined by user in the range of 1<= x<= 999999999 (deprecated)
stpMode	String	No	Self trade prevention mode. Default to cancel maker `cancel_maker`,`cancel_taker`, `cancel_both` Cancel both does not support FOK.
attachAlgoOrds	Array of object	No	TP/SL information attached when placing order
> attachAlgoClOrdId	String	No	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Conditional	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
> tpOrdPx	String	Conditional	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is -1, take-profit will be executed at the market price.
> slTriggerPx	String	Conditional	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
> slOrdPx	String	Conditional	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is -1, stop-loss will be executed at the market price.
> tpTriggerPxType	String	No	Take-profit trigger price type `last`: last price The default is last
> slTriggerPxType	String	No	Stop-loss trigger price type `last`: last price The default is last
> sz	String	Conditional	Size. Only applicable to TP order of split TPs, and it is required for TP order of split TPs
> amendPxOnTriggerType	String	No	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. Whether `slTriggerPx` will move to `avgPx` when the first TP order is triggered `0`: disable, the default value `1`: Enable

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "312269865356374016",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection or success message of event execution.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

ordType
Order type. When creating a new order, you must specify the order type. The order type you specify will affect: 1) what order parameters are required, and 2) how the matching system executes your order. The following are valid order types:
limit: Limit order, which requires specified sz and px.
market: Market order. For SPOT and MARGIN, market order will be filled with market price (by swiping opposite order book). For Expiry Futures and Perpetual Futures, market order will be placed to order book with most aggressive price allowed by Price Limit Mechanism. For OPTION, market order is not supported yet. As the filled price for market orders cannot be determined in advance, OKX reserves/freezes your quote currency by an additional 5% for risk check.
post_only: Post-only order, which the order can only provide liquidity to the market and be a maker. If the order would have executed on placement, it will be canceled instead.
fok: Fill or kill order. If the order cannot be fully filled, the order will be canceled. The order would not be partially filled.
ioc: Immediate or cancel order. Immediately execute the transaction at the order price, cancel the remaining unfilled quantity of the order, and the order quantity will not be displayed in the order book.
optimal_limit_ioc: Market order with ioc (immediate or cancel). Immediately execute the transaction of this market order, cancel the remaining unfilled quantity of the order, and the order quantity will not be displayed in the order book. Only applicable to Expiry Futures and Perpetual Futures.

tgtCcy
This parameter is used to specify the order quantity in the order request is denominated in the quantity of base or quote currency. This is applicable to SPOT Market Orders only.
Base currency: base_ccy
Quote currency: quote_ccy
If you use the Base Currency quantity for buy market orders or the Quote Currency for sell market orders, please note:
1. If the quantity you enter is greater than what you can buy or sell, the system will execute the order according to your maximum buyable or sellable quantity. If you want to trade according to the specified quantity, you should use Limit orders.
2. When the market price is too volatile, the locked balance may not be sufficient to buy the Base Currency quantity or sell to receive the Quote Currency that you specified. We will change the quantity of the order to execute the order based on best effort principle based on your account balance. In addition, we will try to over lock a fraction of your balance to avoid changing the order quantity.
2.1 Example of base currency buy market order:
Taking the market order to buy 10 LTCs as an example, and the user can buy 11 LTC. At this time, if 10 < 11, the order is accepted. When the LTC-USDT market price is 200, and the locked balance of the user is 3,000 USDT, as 200*10 < 3,000, the market order of 10 LTC is fully executed; If the market is too volatile and the LTC-USDT market price becomes 400, 400*10 > 3,000, the user's locked balance is not sufficient to buy using the specified amount of base currency, the user's maximum locked balance of 3,000 USDT will be used to settle the trade. Final transaction quantity becomes 3,000/400 = 7.5 LTC.
2.2 Example of quote currency sell market order:
Taking the market order to sell 1,000 USDT as an example, and the user can sell 1,200 USDT, 1,000 < 1,200, the order is accepted. When the LTC-USDT market price is 200, and the locked balance of the user is 6 LTC, as 1,000/200 < 6, the market order of 1,000 USDT is fully executed; If the market is too volatile and the LTC-USDT market price becomes 100, 100*6 < 1,000, the user's locked balance is not sufficient to sell using the specified amount of quote currency, the user's maximum locked balance of 6 LTC will be used to settle the trade. Final transaction quantity becomes 6 * 100 = 600 USDT.

Mandatory self trade prevention (STP)
The trading platform imposes mandatory self trade prevention at master account level, which means the accounts under the same master account, including master account itself and all its affiliated sub-accounts, will be prevented from self trade. The default STP mode is `Cancel Maker`. Users can also utilize the stpMode request parameter of the placing order endpoint to determine the stpMode of a certain order.
Mandatory self trade prevention will not lead to latency.
There are three STP modes. The STP mode is always taken based on the configuration in the taker order.
1. Cancel Maker: This is the default STP mode, which cancels the maker order to prevent self-trading. Then, the taker order continues to match with the next order based on the order book priority.
2. Cancel Taker: The taker order is canceled to prevent self-trading. If the user's own maker order is lower in the order book priority, the taker order is partially filled and then canceled. FOK orders are always honored and canceled if they would result in self-trading.
3. Cancel Both: Both taker and maker orders are canceled to prevent self-trading. If the user's own maker order is lower in the order book priority, the taker order is partially filled. Then, the remaining quantity of the taker order and the first maker order are canceled. FOK orders are not supported in this mode.

POST / Place multiple orders

Place orders in batches. Maximum 20 orders can be placed per request.
Request parameters should be passed in the form of an array. Orders will be placed in turn

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/batch-orders

Request Example

# batch place order for SPOT
POST /api/v5/trade/batch-orders
body
[
    {
        "instId":"BTC-USDT",
        "tdMode":"cash",
        "clOrdId":"b15",
        "side":"buy",
        "ordType":"limit",
        "px":"2.15",
        "sz":"2"
    },
    {
        "instId":"BTC-USDT",
        "tdMode":"cash",
        "clOrdId":"b16",
        "side":"buy",
        "ordType":"limit",
        "px":"2.15",
        "sz":"2"
    }
]

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Place multiple orders 
place_orders_without_clOrdId = [
    {"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b15", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"},
    {"instId": "BTC-USDT", "tdMode": "cash", "clOrdId": "b16", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"}
]

result = tradeAPI.place_multiple_orders(place_orders_without_clOrdId)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
tdMode	String	Yes	Trade mode `cash`
clOrdId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
side	String	Yes	Order side `buy` `sell`
ordType	String	Yes	Order type `market`: Market order `limit`: Limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
sz	String	Yes	Quantity to buy or sell
px	String	Conditional	Order price. Only applicable to `limit`,`post_only`,`fok`,`ioc`order.
tgtCcy	String	No	Whether the target currency uses the quote or base currency. `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
banAmend	Boolean	No	Whether to disallow the system from amending the size of the SPOT Market Order. Valid options: `true` or `false`. The default value is `false`. If `true`, system will not amend and reject the market order if user does not have sufficient funds. Only applicable to SPOT Market Orders
stpId	String	No	Self trade prevention ID. Orders from the same master account with the same ID will be prevented from self trade. Numerical integers defined by user in the range of 1<= x<= 999999999 (deprecated)
stpMode	String	No	Self trade prevention mode. Default to cancel maker `cancel_maker`,`cancel_taker`, `cancel_both` Cancel both does not support FOK.
attachAlgoOrds	Array of object	No	TP/SL information attached when placing order
> attachAlgoClOrdId	String	No	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Conditional	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
> tpOrdPx	String	Conditional	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is -1, take-profit will be executed at the market price.
> slTriggerPx	String	Conditional	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
> slOrdPx	String	Conditional	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is -1, stop-loss will be executed at the market price.
> tpTriggerPxType	String	No	Take-profit trigger price type `last`: last price The default is last
> slTriggerPxType	String	No	Stop-loss trigger price type `last`: last price The default is last
> sz	String	Conditional	Size. Only applicable to TP order of split TPs, and it is required for TP order of split TPs
> amendPxOnTriggerType	String	No	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. Whether `slTriggerPx` will move to `avgPx` when the first TP order is triggered `0`: disable, the default value `1`: Enable

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "tag":"",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "tag":"",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection or success message of event execution.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

POST / Cancel order

Cancel an incomplete order.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/cancel-order

Request Example

POST /api/v5/trade/cancel-order
body
{
    "ordId":"590908157585625111",
    "instId":"BTC-USDT"
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Cancel order
result = tradeAPI.cancel_order(instId="BTC-USDT", ordId = "590908157585625111")
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required. If both are passed, ordId will be used.
clOrdId	String	Conditional	Client Order ID as assigned by the client

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection message if the request is unsuccessful.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

POST / Cancel multiple orders

Cancel incomplete orders in batches. Maximum 20 orders can be canceled per request. Request parameters should be passed in the form of an array.

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/cancel-batch-orders

Request Example

POST /api/v5/trade/cancel-batch-orders
body
[
    {
        "instId":"BTC-USDT",
        "ordId":"590908157585625111"
    },
    {
        "instId":"BTC-USDT",
        "ordId":"590908544950571222"
    }
]

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Cancel multiple orders by ordId
cancel_orders_with_orderId = [
    {"instId": "BTC-USDT", "ordId": "590908157585625111"},
    {"instId": "BTC-USDT", "ordId": "590908544950571222"}
]

result = tradeAPI.cancel_multiple_orders(cancel_orders_with_orderId)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required. If both are passed, `ordId` will be used.
clOrdId	String	Conditional	Client Order ID as assigned by the client

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection message if the request is unsuccessful.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

POST / Amend order

Amend an incomplete order.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/amend-order

Request Example

POST /api/v5/trade/amend-order
body
{
    "ordId":"590909145319051111",
    "newSz":"2",
    "instId":"BTC-USDT"
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Amend order
result = tradeAPI.amend_order(
    instId="BTC-USDT",
    ordId="590909145319051111",
    newSz="2"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID
cxlOnFail	Boolean	No	Whether the order needs to be automatically canceled when the order amendment fails Valid options: `false` or `true`, the default is `false`.
ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required. If both are passed, `ordId` will be used.
clOrdId	String	Conditional	Client Order ID as assigned by the client
reqId	String	No	Client Request ID as assigned by the client for order amendment A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. The response will include the corresponding `reqId` to help you identify the request if you provide it in the request.
newSz	String	Conditional	New quantity after amendment. When amending a partially-filled order, the `newSz` should include the amount that has been filled.
newPx	String	Conditional	New price after amendment.
attachAlgoOrds	Array of object	No	TP/SL information attached when placing order
> attachAlgoId	String	Conditional	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
> attachAlgoClOrdId	String	Conditional	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> newTpTriggerPx	String	Conditional	Take-profit trigger price. Either the take profit trigger price or order price is 0, it means that the take profit is deleted. Only applicable to Expiry Futures and Perpetual Futures.
> newTpOrdPx	String	Conditional	Take-profit order price If the price is -1, take-profit will be executed at the market price. Only applicable to Expiry Futures and Perpetual Futures.
> newSlTriggerPx	String	Conditional	Stop-loss trigger price Either the stop loss trigger price or order price is 0, it means that the stop loss is deleted. Only applicable to Expiry Futures and Perpetual Futures.
> newSlOrdPx	String	Conditional	Stop-loss order price If the price is -1, stop-loss will be executed at the market price. Only applicable to Expiry Futures and Perpetual Futures.
> newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price Only applicable to `FUTURES`/`SWAP` If you want to add the take-profit, this parameter is required
> newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price Only applicable to `FUTURES`/`SWAP` If you want to add the stop-loss, this parameter is required
> sz	String	Conditional	New size. Only applicable to TP order of split TPs, and it is required for TP order of split TPs
> amendPxOnTriggerType	String	No	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
         "clOrdId":"",
         "ordId":"12344",
         "reqId":"b12344",
         "sCode":"0",
         "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> reqId	String	Client Request ID as assigned by the client for order amendment.
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection message if the request is unsuccessful.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

POST / Amend multiple orders

Amend incomplete orders in batches. Maximum 20 orders can be amended per request. Request parameters should be passed in the form of an array.

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

Rate limit of this endpoint will also be affected by the rules Sub-account rate limit and Fill ratio based sub-account rate limit.

HTTP Request

POST /api/v5/trade/amend-batch-orders

Request Example

POST /api/v5/trade/amend-batch-orders
body
[
    {
        "ordId":"590909308792049444",
        "newSz":"2",
        "instId":"BTC-USDT"
    },
    {
        "ordId":"590909308792049555",
        "newSz":"2",
        "instId":"BTC-USDT"
    }
]

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Amend incomplete orders in batches by ordId
amend_orders_with_orderId = [
    {"instId": "BTC-USDT", "ordId": "590909308792049444","newSz":"2"},
    {"instId": "BTC-USDT", "ordId": "590909308792049555","newSz":"2"}
]

result = tradeAPI.amend_multiple_orders(amend_orders_with_orderId)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID
cxlOnFail	Boolean	No	Whether the order needs to be automatically canceled when the order amendment fails `false` `true`, the default is `false`.
ordId	String	Conditional	Order ID Either `ordId` or `clOrdId`is required, if both are passed, `ordId` will be used.
clOrdId	String	Conditional	Client Order ID as assigned by the client
reqId	String	No	Client Request ID as assigned by the client for order amendment A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. The response will include the corresponding `reqId` to help you identify the request if you provide it in the request.
newSz	String	Conditional	New quantity after amendment. When amending a partially-filled order, the `newSz` should include the amount that has been filled.
newPx	String	Conditional	New price after amendment.
attachAlgoOrds	Array of object	No	TP/SL information attached when placing order
> attachAlgoId	String	Conditional	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
> attachAlgoClOrdId	String	Conditional	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> newTpTriggerPx	String	Conditional	Take-profit trigger price. Either the take profit trigger price or order price is 0, it means that the take profit is deleted. Only applicable to Expiry Futures and Perpetual Futures.
> newTpOrdPx	String	Conditional	Take-profit order price If the price is -1, take-profit will be executed at the market price. Only applicable to Expiry Futures and Perpetual Futures.
> newSlTriggerPx	String	Conditional	Stop-loss trigger price Either the stop loss trigger price or order price is 0, it means that the stop loss is deleted. Only applicable to Expiry Futures and Perpetual Futures.
> newSlOrdPx	String	Conditional	Stop-loss order price If the price is -1, stop-loss will be executed at the market price. Only applicable to Expiry Futures and Perpetual Futures.
> newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price Only applicable to `FUTURES`/`SWAP` If you want to add the take-profit, this parameter is required
> newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price Only applicable to `FUTURES`/`SWAP` If you want to add the stop-loss, this parameter is required
> sz	String	Conditional	New size. Only applicable to TP order of split TPs, and it is required for TP order of split TPs
> amendPxOnTriggerType	String	No	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        }
    ],
    "inTime": "1695190491421339",
    "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
code	String	The result code, `0` means success
msg	String	The error message, empty if the code is 0
data	Array of objects	Array of objects contains the response results
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> reqId	String	Client Request ID as assigned by the client for order amendment.
> sCode	String	The code of the event execution result, `0` means success.
> sMsg	String	Rejection message if the request is unsuccessful.
inTime	String	Timestamp at REST gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123` The time is recorded after authentication.
outTime	String	Timestamp at REST gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

GET / Order details

Retrieve order details.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

GET /api/v5/trade/order

Request Example

GET /api/v5/trade/order?ordId=1753197687182819328&instId=BTC-USDT

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve order details by ordId
result = tradeAPI.get_order(
    instId="BTC-USDT",
    ordId="680800019749904384"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT` Only applicable to live instruments
ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required, if both are passed, `ordId` will be used
clOrdId	String	Conditional	Client Order ID as assigned by the client If the `clOrdId` is associated with multiple orders, only the latest one will be returned.

Response Example

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.00192834",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "51858",
            "cTime": "1708587373361",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "-0.00000192834",
            "feeCcy": "BTC",
            "fillPx": "51858",
            "fillSz": "0.00192834",
            "fillTime": "1708587373361",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",
            "posSide": "net",
            "px": "",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type `SPOT`
instId	String	Instrument ID
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
tag	String	Order tag
px	String	Price For options, use coin as unit (e.g. BTC, ETH)
pxUsd	String	Options price in USDOnly applicable to options; return "" for other instrument types
pxVol	String	Implied volatility of the options orderOnly applicable to options; return "" for other instrument types
pxType	String	Price type of options `px`: Place an order based on price, in the unit of coin (the unit for the request parameter px is BTC or ETH) `pxVol`: Place an order based on pxVol `pxUsd`: Place an order based on pxUsd, in the unit of USD (the unit for the request parameter px is USD)
sz	String	Quantity to buy or sell
pnl	String	Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
ordType	String	Order type `market`: Market order `limit`: Limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order `optimal_limit_ioc`: Market order with immediate-or-cancel order `mmp`: Market Maker Protection (only applicable to Option in Portfolio Margin mode) `mmp_and_post_only`: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode) `op_fok`: Simple options (fok)
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
accFillSz	String	Accumulated fill quantity The unit is `base_ccy` for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`; The unit is contract for `FUTURES`/`SWAP`/`OPTION`
fillPx	String	Last filled price. If none is filled, it will return "".
tradeId	String	Last traded ID
fillSz	String	Last filled quantity The unit is `base_ccy` for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`; The unit is contract for `FUTURES`/`SWAP`/`OPTION`
fillTime	String	Last filled time
avgPx	String	Average filled price. If none is filled, it will return "".
state	String	State `canceled` `live` `partially_filled` `filled` `mmp_canceled`
stpId	String	Self trade prevention ID Return "" if self trade prevention is not applicable (deprecated)
stpMode	String	Self trade prevention mode Return "" if self trade prevention is not applicable
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL.
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
attachAlgoOrds	Array of object	TP/SL information attached when placing order
> attachAlgoId	String	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price.
> sz	String	Size. Only applicable to TP order of split TPs
> amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
linkedAlgoOrd	Object	Linked SL order detail, only applicable to the order that is placed by one-cancels-the-other (OCO) order that contains the TP limit order.
> algoId	Object	Algo ID
feeCcy	String	Fee currency
fee	String	Fee and rebate For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01. For Expiry Futures, Perpetual Futures and Options, it is accumulated fee and rebate
rebateCcy	String	Rebate currency
source	String	Order source `6`: The normal order triggered by the `trigger order` `7`:The normal order triggered by the `TP/SL order` `13`: The normal order triggered by the algo order `25`:The normal order triggered by the `trailing stop order`
rebate	String	Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
category	String	Category `normal` `twap` `adl` `full_liquidation` `partial_liquidation` `delivery` `ddh`: Delta dynamic hedge
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
cancelSource	String	Code of the cancellation source.
cancelSourceReason	String	Reason for the cancellation.
quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
algoClOrdId	String	Client-supplied Algo ID. There will be a value when algo order attaching `algoClOrdId` is triggered, or it will be "".
algoId	String	Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET / Order List

Retrieve all incomplete orders under the current account.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-pending

Request Example

GET /api/v5/trade/orders-pending?ordType=post_only,fok,ioc&instType=SPOT

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve all incomplete orders
result = tradeAPI.get_order_list(
    instType="SPOT",
    ordType="post_only,fok,ioc"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
ordType	String	No	Order type `market`: Market order `limit`: Limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
state	String	No	State `live` `partially_filled`
after	String	No	Pagination of data to return records earlier than the requested `ordId`
before	String	No	Pagination of data to return records newer than the requested `ordId`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "",
            "cTime": "1724733617998",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "0",
            "feeCcy": "BTC",
            "fillPx": "",
            "fillSz": "0",
            "fillTime": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "1752588852617379840",
            "ordType": "post_only",
            "pnl": "0",
            "posSide": "net",
            "px": "13013.5",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "live",
            "stpId": "",
            "stpMode": "cancel_maker",
            "sz": "0.001",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "",
            "uTime": "1724733617998"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
tag	String	Order tag
px	String	Price For options, use coin as unit (e.g. BTC, ETH)
pxUsd	String	Options price in USDOnly applicable to options; return "" for other instrument types
pxVol	String	Implied volatility of the options orderOnly applicable to options; return "" for other instrument types
pxType	String	Price type of options `px`: Place an order based on price, in the unit of coin (the unit for the request parameter px is BTC or ETH) `pxVol`: Place an order based on pxVol `pxUsd`: Place an order based on pxUsd, in the unit of USD (the unit for the request parameter px is USD)
sz	String	Quantity to buy or sell
pnl	String	Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
ordType	String	Order type `market`: Market order `limit`: Limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order `optimal_limit_ioc`: Market order with immediate-or-cancel order `mmp`: Market Maker Protection (only applicable to Option in Portfolio Margin mode) `mmp_and_post_only`: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode) `op_fok`: Simple options (fok)
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
accFillSz	String	Accumulated fill quantity
fillPx	String	Last filled price
tradeId	String	Last trade ID
fillSz	String	Last filled quantity
fillTime	String	Last filled time
avgPx	String	Average filled price. If none is filled, it will return "".
state	String	State `live` `partially_filled`
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL.
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
attachAlgoOrds	Array of object	TP/SL information attached when placing order
> attachAlgoId	String	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price.
> sz	String	Size. Only applicable to TP order of split TPs
> amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
stpId	String	Self trade prevention ID Return "" if self trade prevention is not applicable (deprecated)
stpMode	String	Self trade prevention mode Return "" if self trade prevention is not applicable
feeCcy	String	Fee currency
fee	String	Fee and rebate For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01. For Expiry Futures, Perpetual Futures and Options, it is accumulated fee and rebate
rebateCcy	String	Rebate currency
source	String	Order source `6`: The normal order triggered by the `trigger order` `7`:The normal order triggered by the `TP/SL order` `13`: The normal order triggered by the algo order `25`:The normal order triggered by the `trailing stop order`
rebate	String	Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
category	String	Category `normal`
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
algoClOrdId	String	Client-supplied Algo ID. There will be a value when algo order attaching `algoClOrdId` is triggered, or it will be "".
algoId	String	Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cancelSource	String	Code of the cancellation source.
cancelSourceReason	String	Reason for the cancellation.

GET / Order history (last 7 days)

Get completed orders which are placed in the last 7 days, including those placed 7 days ago but completed in the last 7 days.

The incomplete orders that have been canceled are only reserved for 2 hours.

Rate Limit: 40 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-history

Request Example

GET /api/v5/trade/orders-history?ordType=post_only,fok,ioc&instType=SPOT

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Get completed SPOT orders which are placed in the last 7 days
# The incomplete orders that have been canceled are only reserved for 2 hours
result = tradeAPI.get_orders_history(
    instType="SPOT",
    ordType="post_only,fok,ioc"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	yes	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
ordType	String	No	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
state	String	No	State `canceled` `filled` `mmp_canceled`: Order canceled automatically due to Market Maker Protection
after	String	No	Pagination of data to return records earlier than the requested `ordId`
before	String	No	Pagination of data to return records newer than the requested `ordId`
begin	String	No	Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "accFillSz": "0.00192834",
            "algoClOrdId": "",
            "algoId": "",
            "attachAlgoClOrdId": "",
            "attachAlgoOrds": [],
            "avgPx": "51858",
            "cTime": "1708587373361",
            "cancelSource": "",
            "cancelSourceReason": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "-0.00000192834",
            "feeCcy": "BTC",
            "fillPx": "51858",
            "fillSz": "0.00192834",
            "fillTime": "1708587373361",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "isTpLimit": "false",
            "lever": "",
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",
            "posSide": "",
            "px": "",
            "pxType": "",
            "pxUsd": "",
            "pxVol": "",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "USDT",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
tag	String	Order tag
px	String	Price For options, use coin as unit (e.g. BTC, ETH)
pxUsd	String	Options price in USDOnly applicable to options; return "" for other instrument types
pxVol	String	Implied volatility of the options orderOnly applicable to options; return "" for other instrument types
pxType	String	Price type of options `px`: Place an order based on price, in the unit of coin (the unit for the request parameter px is BTC or ETH) `pxVol`: Place an order based on pxVol `pxUsd`: Place an order based on pxUsd, in the unit of USD (the unit for the request parameter px is USD)
sz	String	Quantity to buy or sell
ordType	String	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order `optimal_limit_ioc`: Market order with immediate-or-cancel order `mmp`: Market Maker Protection (only applicable to Option in Portfolio Margin mode) `mmp_and_post_only`: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode) `op_fok`: Simple options (fok)
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
accFillSz	String	Accumulated fill quantity
fillPx	String	Last filled price. If none is filled, it will return "".
tradeId	String	Last trade ID
fillSz	String	Last filled quantity
fillTime	String	Last filled time
avgPx	String	Average filled price. If none is filled, it will return "".
state	String	State `canceled` `filled` `mmp_canceled`
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL.
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
attachAlgoOrds	Array of object	TP/SL information attached when placing order
> attachAlgoId	String	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price.
> sz	String	Size. Only applicable to TP order of split TPs
> amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
stpId	String	Self trade prevention ID Return "" if self trade prevention is not applicable (deprecated)
stpMode	String	Self trade prevention mode Return "" if self trade prevention is not applicable
feeCcy	String	Fee currency
fee	String	Fee and rebate For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01. For Expiry Futures, Perpetual Futures and Options, it is accumulated fee and rebate
rebateCcy	String	Rebate currency
source	String	Order source `6`: The normal order triggered by the `trigger order` `7`:The normal order triggered by the `TP/SL order` `13`: The normal order triggered by the algo order `25`:The normal order triggered by the `trailing stop order`
rebate	String	Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
pnl	String	Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
category	String	Category `normal` `twap` `adl` `full_liquidation` `partial_liquidation` `delivery` `ddh`: Delta dynamic hedge
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
cancelSource	String	Code of the cancellation source.
cancelSourceReason	String	Reason for the cancellation.
algoClOrdId	String	Client-supplied Algo ID. There will be a value when algo order attaching `algoClOrdId` is triggered, or it will be "".
algoId	String	Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get / Order history (last 3 months)

Retrieve the completed order data of the last 3 months, and the incomplete orders that have been canceled are only reserved for 2 hours.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-history-archive

Request Example

GET /api/v5/trade/orders-history-archive?ordType=post_only,fok,ioc&instType=SPOT

Request Parameters

Parameter	Type	Required	Description
instType	String	yes	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
ordType	String	No	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
state	String	No	State `canceled` `filled`
category	String	No	Category `twap`
after	String	No	Pagination of data to return records earlier than the requested `ordId`
before	String	No	Pagination of data to return records newer than the requested `ordId`
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instType": "SPOT",
      "instId": "BTC-USDT",
      "ccy": "",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "posSide": "",
      "tdMode": "cash",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "filled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpTriggerPxType": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slTriggerPxType": "",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "pnl": "",
      "category": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
ccy	String	Margin currency
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
tag	String	Order tag
px	String	Price
sz	String	Quantity to buy or sell
ordType	String	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
accFillSz	String	Accumulated fill quantity
fillPx	String	Last filled price. If none is filled, it will return `0`.
tradeId	String	Last trade ID
fillSz	String	Last filled quantity
fillTime	String	Last filled time
avgPx	String	Average filled price. If none is filled, it will return "".
state	String	State `canceled` `filled`
lever	String	Leverage, from `0.01` to `125`
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
feeCcy	String	Fee currency
fee	String	Fee
rebateCcy	String	Rebate currency
rebate	String	Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
pnl	String	Profit and loss
category	String	Category `normal`
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET / Transaction details (last 3 days)

Retrieve recently-filled transaction details in the last 3 day.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/fills

Request Example

GET /api/v5/trade/fills

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve recently-filled transaction details
result = tradeAPI.get_fills()
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
ordId	String	No	Order ID
after	String	No	Pagination of data to return records earlier than the requested `billId`
before	String	No	Pagination of data to return records newer than the requested `billId`
begin	String	No	Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",
            "fillPxVol": "",
            "fillFwdPx": "",
            "fee": "-0.00000192834",
            "fillPnl": "0",
            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",
            "fillPxUsd": "",
            "instId": "BTC-USDT",
            "clOrdId": "",
            "posSide": "net",
            "billId": "680800019754098688",
            "fillMarkVol": "",
            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",
            "fillIdxPx": "",
            "tradeId": "744876980",
            "fillMarkPx": "",
            "feeCcy": "BTC",
            "ts": "1708587373362"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tradeId	String	Last trade ID
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
billId	String	Bill ID
tag	String	Order tag
fillPx	String	Last filled price
fillSz	String	Last filled quantity
fillIdxPx	String	Index price at the moment of trade execution For cross currency spot pairs, it returns baseCcy-USDT index price. For example, for LTC-ETH, this field returns the index price of LTC-USDT.
fillPnl	String	Last filled profit and loss, applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
fillPxVol	String	Implied volatility when filled Only applicable to options; return "" for other instrument types
fillPxUsd	String	Options price when filled, in the unit of USD Only applicable to options; return "" for other instrument types
fillMarkVol	String	Mark volatility when filled Only applicable to options; return "" for other instrument types
fillFwdPx	String	Forward price when filled Only applicable to options; return "" for other instrument types
fillMarkPx	String	Mark price when filled Applicable to `FUTURES`, `SWAP`, `OPTION`
side	String	Order side, `buy` `sell`
posSide	String	Position side `long` `short` it returns `net` in`net` mode.
execType	String	Liquidity taker or maker `T`: taker `M`: maker Not applicable to system orders such as ADL and liquidation
feeCcy	String	Trading fee or rebate currency
fee	String	The amount of trading fee or rebate. The trading fee deduction is negative, such as '-0.01'; the rebate is positive, such as '0.01'.
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.
fillTime	String	Trade time which is the same as `fillTime` for the order channel.
feeRate	String	Fee rate. This field is returned for `SPOT` and `MARGIN` only

GET / Transaction details (last 3 months)

Retrieve recently-filled transaction details in the last 3 months.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/fills-history

Request Example

GET /api/v5/trade/fills-history?instType=SPOT

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve SPOT transaction details in the last 3 months.
result = tradeAPI.get_fills_history(
    instType="SPOT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	YES	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
ordId	String	No	Order ID
after	String	No	Pagination of data to return records earlier than the requested `billId`
before	String	No	Pagination of data to return records newer than the requested `billId`
begin	String	No	Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",
            "fillPxVol": "",
            "fillFwdPx": "",
            "fee": "-0.00000192834",
            "fillPnl": "0",
            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",
            "fillPxUsd": "",
            "instId": "BTC-USDT",
            "clOrdId": "",
            "posSide": "net",
            "billId": "680800019754098688",
            "fillMarkVol": "",
            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",
            "fillIdxPx": "",
            "tradeId": "744876980",
            "fillMarkPx": "",
            "feeCcy": "BTC",
            "ts": "1708587373362"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tradeId	String	Last trade ID
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
billId	String	Bill ID
tag	String	Order tag
fillPx	String	Last filled price
fillSz	String	Last filled quantity
fillIdxPx	String	Index price at the moment of trade execution For cross currency spot pairs, it returns baseCcy-USDT index price. For example, for LTC-ETH, this field returns the index price of LTC-USDT.
fillPnl	String	Last filled profit and loss, applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
fillPxVol	String	Implied volatility when filled Only applicable to options; return "" for other instrument types
fillPxUsd	String	Options price when filled, in the unit of USD Only applicable to options; return "" for other instrument types
fillMarkVol	String	Mark volatility when filled Only applicable to options; return "" for other instrument types
fillFwdPx	String	Forward price when filled Only applicable to options; return "" for other instrument types
fillMarkPx	String	Mark price when filled Applicable to `FUTURES`, `SWAP`, `OPTION`
side	String	Order side `buy` `sell`
posSide	String	Position side `long` `short` it returns `net` in`net` mode.
execType	String	Liquidity taker or maker `T`: taker `M`: maker Not applicable to system orders such as ADL and liquidation
feeCcy	String	Trading fee or rebate currency
fee	String	The amount of trading fee or rebate. The trading fee deduction is negative, such as '-0.01'; the rebate is positive, such as '0.01'.
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.
fillTime	String	Trade time which is the same as `fillTime` for the order channel.
feeRate	String	Fee rate. This field is returned for `SPOT` and `MARGIN` only

POST / Transaction details (in the past 2 years)

Apply for recently-filled transaction details in the past 2 years except for last 3 months.

Rate Limit: 10 requests per day

Rate limit rule: UserID

Permissions: Read

HTTP Request

POST /api/v5/trade/fills-archive

Request Example

POST /api/v5/trade/fills-archive
body
{
    "year":"2023",
    "quarter":"Q1"
}

Request Parameters

Parameter	Type	Required	Description
year	String	Yes	4 digits year
quarter	String	Yes	Quarter, valid value is `Q1`, `Q2`, `Q3`, `Q4`

Response Example

{
    "code": "0",
    "data": [
        {
            "result": "true",
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
result	String	Whether there is already a download link for this section `true`: Existed, can check from "Get download link". `false`: Does not exist and is generating, can check the download link after 30 hours
ts	String	Download link generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET / Transaction details (in the past 2 years)

Retrieve recently-filled transaction details in the past 2 years except for last 3 months.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/trade/fills-archive

Request Example

GET /api/v5/trade/fills-archive?year=2023&quarter=Q4

Request Parameters

Parameter	Type	Required	Description
year	String	Yes	4 digits year
quarter	String	Yes	Quarter, valid value is `Q1`, `Q2`, `Q3`, `Q4`

Response Example

{
    "code": "0",
    "data": [
        {
            "fileHref": "http://xxx",
            "state": "finished",
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
fileHref	String	Download file link
ts	String	Download link generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
state	String	Download link status "finished" "ongoing"

Field descriptions in the decompressed CSV file

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
tradeId	String	Last trade ID
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
billId	String	Bill ID
tag	String	Order tag
fillPx	String	Last filled price
fillSz	String	Last filled quantity
side	String	Order side, `buy` `sell`
posSide	String	Position side `long` `short` it returns `net` in`net` mode.
execType	String	Liquidity taker or maker `T`: taker `M`: maker Not applicable to system orders such as ADL and liquidation
feeCcy	String	Trading fee or rebate currency
fee	String	The amount of trading fee or rebate. The trading fee deduction is negative, such as '-0.01'; the rebate is positive, such as '0.01'.
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.
subType	String	Transaction type

GET / Easy convert currency list

Get list of small convertibles and mainstream currencies. Only applicable to the crypto balance less than $10.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/easy-convert-currency-list

Request Example

GET /api/v5/trade/easy-convert-currency-list

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Get list of small convertibles and mainstream currencies
result = tradeAPI.get_easy_convert_currency_list()
print(result)

Request Parameters

None

Response Example

{
    "code": "0",
    "data": [
        {
            "fromData": [
                {
                    "fromAmt": "6.580712708344864",
                    "fromCcy": "ADA"
                },
                {
                    "fromAmt": "2.9970000013055097",
                    "fromCcy": "USDC"
                }
            ],
            "toCcy": [
                "USDT",
                "BTC",
                "ETH",
                "OKB"
            ]
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
fromData	Array	Currently owned and convertible small currency list
> fromCcy	String	Type of small payment currency convert from, e.g. BTC
> fromAmt	String	Amount of small payment currency convert from
toCcy	Array	Type of mainstream currency convert to, e.g. USDT

POST / Place easy convert

Convert small currencies to mainstream currencies.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/trade/easy-convert

Request Example

POST /api/v5/trade/easy-convert
body
{
    "fromCcy": ["ADA","USDC"], //Seperated by commas
    "toCcy": "OKB" 
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Convert small currencies to mainstream currencies
result = tradeAPI.easy_convert(
    fromCcy=["ADA", "USDC"],
    toCcy="OKB"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
fromCcy	Array	Yes	Type of small payment currency convert from Maximum 5 currencies can be selected in one order. If there are multiple currencies, separate them with commas.
toCcy	String	Yes	Type of mainstream currency convert to Only one receiving currency type can be selected in one order and cannot be the same as the small payment currencies.

Response Example

{
    "code": "0",
    "data": [
        {
            "fillFromSz": "6.5807127",
            "fillToSz": "0.17171580105126",
            "fromCcy": "ADA",
            "status": "running",
            "toCcy": "OKB",
            "uTime": "1661419684687"
        },
        {
            "fillFromSz": "2.997",
            "fillToSz": "0.1683755161661844",
            "fromCcy": "USDC",
            "status": "running",
            "toCcy": "OKB",
            "uTime": "1661419684687"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
status	String	Current status of easy convert `running`: Running `filled`: Filled `failed`: Failed
fromCcy	String	Type of small payment currency convert from
toCcy	String	Type of mainstream currency convert to
fillFromSz	String	Filled amount of small payment currency convert from
fillToSz	String	Filled amount of mainstream currency convert to
uTime	String	Trade time, Unix timestamp format in milliseconds, e.g. 1597026383085

GET / Easy convert history

Get the history and status of easy convert trades.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/easy-convert-history

Request Example

GET /api/v5/trade/easy-convert-history

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Get the history of easy convert trades
result = tradeAPI.get_easy_convert_history()
print(result)

Request Parameters

Parameter	Type	Required	Description
after	String	No	Pagination of data to return records earlier than the requested time, Unix timestamp format in milliseconds, e.g. 1597026383085
before	String	No	Pagination of data to return records newer than the requested time, Unix timestamp format in milliseconds, e.g. 1597026383085
limit	String	No	Number of results per request. The maximum is 100. The default is 100.

Response Example

{
    "code": "0",
    "data": [
        {
            "fillFromSz": "0.1761712511667539",
            "fillToSz": "6.7342205900000000",
            "fromCcy": "OKB",
            "status": "filled",
            "toCcy": "ADA",
            "acct": "18",
            "uTime": "1661313307979"
        },
        {
            "fillFromSz": "0.1722106121112177",
            "fillToSz": "2.9971018300000000",
            "fromCcy": "OKB",
            "status": "filled",
            "toCcy": "USDC",
            "acct": "18",
            "uTime": "1661313307979"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
fromCcy	String	Type of small payment currency convert from
fillFromSz	String	Amount of small payment currency convert from
toCcy	String	Type of mainstream currency convert to
fillToSz	String	Amount of mainstream currency convert to
acct	String	The account where the mainstream currency is located `6`: Funding account `18`: Trading account
status	String	Current status of easy convert `running`: Running `filled`: Filled `failed`: Failed
uTime	String	Trade time, Unix timestamp format in milliseconds, e.g. `1597026383085`

POST / Cancel All After

Cancel all pending orders after the countdown timeout. Applicable to all trading symbols through order book (except Spread trading)

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/trade/cancel-all-after

Request Example

POST /api/v5/trade/cancel-all-after
{
   "timeOut":"60"
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Set cancel all after
result = tradeAPI.cancel_all_after(
    timeOut="10"
)

print(result)

Request Parameters

Parameter	Type	Required	Description
timeOut	String	Yes	The countdown for order cancellation, with second as the unit. Range of value can be 0, [10, 120]. Setting timeOut to 0 disables Cancel All After.
tag	String	No	CAA order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "triggerTime":"1587971460",
            "tag":"",
            "ts":"1587971400"
        }
    ]
}

Response Parameters

Parameter	Type	Description
triggerTime	String	The time the cancellation is triggered. triggerTime=0 means Cancel All After is disabled.
tag	String	CAA order tag
ts	String	The time the request is received.

Please note that tag level CAA does not apply to `mmp` and `mmp_and_post _only` order types.

To use tag level CAA, first, users need to set tags for their orders using the `tag` request parameter in the placing orders endpoint. When calling the CAA endpoint, if the `tag` request parameter is not provided, the default will be to set CAA at the account level. In this case, all pending orders for all order book trading symbols under that sub-account will be cancelled when CAA triggers, consistent with the existing logic. If the `tag` request parameter is provided, CAA will be set at the order tag level. When triggered, only pending orders of order book trading symbols with the specified tag will be canceled, while orders with other tags or no tags will remain unaffected.

Users can run a maximum of 20 tag level CAAs simultaneously under the same sub-account. The system will only count live tag level CAAs. CAAs that have been triggered or revoked by the user will not be counted. The user will receive error code 51071 when exceeding the limit.

GET / Account rate limit

Get account rate limit related information.

Only new order requests and amendment order requests will be counted towards this limit. For batch order requests consisting of multiple orders, each order will be counted individually.

For details, please refer to Fill ratio based sub-account rate limit

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Requests

GET /api/v5/trade/account-rate-limit

Request Example

# Get the account rate limit
GET /api/v5/trade/account-rate-limit

Request Parameters

None

Response Example

{
   "code":"0",
   "data":[
      {
         "accRateLimit":"2000",
         "fillRatio":"0.1234",
         "mainFillRatio":"0.1234",
         "nextAccRateLimit":"2000",
         "ts":"123456789000"
      }
   ],
   "msg":""
}

Response Parameters

Parameter	Type	Description
fillRatio	String	Sub account fill ratio during the monitoring period Applicable for users with trading fee level >= VIP 5 and return "" for others For accounts with no trading volume during the monitoring period, return "0". For accounts with trading volume but no order count due to our counting logic, return "9999".
mainFillRatio	String	Master account aggregated fill ratio during the monitoring period Applicable for users with trading fee level >= VIP 5 and return "" for others For accounts with no trading volume during the monitoring period, return "0"
accRateLimit	String	Current sub-account rate limit per two seconds
nextAccRateLimit	String	Expected sub-account rate limit (per two seconds) in the next period Applicable for users with trading fee level >= VIP 5 and return "" for others
ts	String	Data update time For users with trading fee level >= VIP 5, the data will be generated at 08:00 am (UTC) For users with trading fee level < VIP 5, return the current timestamp

WS / Order channel

Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when there are order updates.

URL Path

/ws/v5/private (required login)

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "orders",
      "instType": "ANY"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `orders`
> instType	String	Yes	Instrument type `ANY`
> instId	String	No	Instrument ID

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders",
    "instType": "ANY"
  },
  "connId": "a4d3ae55"
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders",
    "instType": "ANY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders\", \"instType\" : \"FUTURES\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instType	String	Yes	Instrument type `ANY`
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "orders",
        "instType": "ANY",
        "uid": "614488474791936"
    },
    "data": [
        {
            "accFillSz": "0.001",
            "algoClOrdId": "",
            "algoId": "",
            "amendResult": "",
            "amendSource": "",
            "avgPx": "31527.1",
            "cancelSource": "",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "code": "0",
            "cTime": "1654084334977",
            "execType": "M",
            "fee": "-0.02522168",
            "feeCcy": "USDT",
            "fillFee": "-0.02522168",
            "fillFeeCcy": "USDT",
            "fillNotionalUsd": "31.50818374",
            "fillPx": "31527.1",
            "fillSz": "0.001",
            "fillPnl": "0.01",
            "fillTime": "1654084353263",
            "fillPxVol": "",
            "fillPxUsd": "",
            "fillMarkVol": "",
            "fillFwdPx": "",
            "fillMarkPx": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "0",
            "msg": "",
            "notionalUsd": "31.50818374",
            "ordId": "452197707845865472",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "",
            "px": "31527.1",
            "pxUsd":"",
            "pxVol":"",
            "pxType":"",
            "quickMgnType": "",
            "rebate": "0",
            "rebateCcy": "BTC",
            "reduceOnly": "false",
            "reqId": "",
            "side": "sell",
            "attachAlgoClOrdId": "",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "last",
            "source": "",
            "state": "filled",
            "stpId": "",
            "stpMode": "",
            "sz": "0.001",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "last",
            "attachAlgoOrds": [],
            "tradeId": "242589207",
            "lastPx": "38892.2",
            "uTime": "1654084353264"
        }
    ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> uid	String	User Identifier
> instType	String	Instrument type
> instFamily	String	Instrument family
> instId	String	Instrument ID
data	Array	Subscribed data
> instType	String	Instrument type
> instId	String	Instrument ID
> tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market orders. Default is `quote_ccy` for buy, `base_ccy` for sell
> ccy	String	Margin currency Only applicable to cross `MARGIN` orders in `Spot and futures mode`.
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> px	String	Price For options, use coin as unit (e.g. BTC, ETH)
> pxUsd	String	Options price in USDOnly applicable to options; return "" for other instrument types
> pxVol	String	Implied volatility of the options orderOnly applicable to options; return "" for other instrument types
> pxType	String	Price type of options `px`: Place an order based on price, in the unit of coin (the unit for the request parameter px is BTC or ETH) `pxVol`: Place an order based on pxVol `pxUsd`: Place an order based on pxUsd, in the unit of USD (the unit for the request parameter px is USD)
> sz	String	The original order quantity, `SPOT`/`MARGIN`, in the unit of currency; `FUTURES`/`SWAP`/`OPTION`, in the unit of contract
> notionalUsd	String	Estimated national value in `USD` of order
> ordType	String	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order `optimal_limit_ioc`: Market order with immediate-or-cancel order (applicable only to Expiry Futures and Perpetual Futures) `mmp`: Market Maker Protection (only applicable to Option in Portfolio Margin mode) `mmp_and_post_only`: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode). `op_fok`: Simple options (fok)
> side	String	Order side, `buy` `sell`
> posSide	String	Position side `net` `long` or `short` Only applicable to `FUTURES`/`SWAP`
> tdMode	String	Trade mode, `cross`: cross `isolated`: isolated `cash`: cash
> fillPx	String	Last filled price
> tradeId	String	Last trade ID
> fillSz	String	Last filled quantity The unit is `base_ccy` for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`; The unit is contract for `FUTURES`/`SWAP`/`OPTION`
> fillPnl	String	Last filled profit and loss, applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
> fillTime	String	Last filled time
> fillFee	String	last filled fee amount or rebate amount: Negative number represents the user transaction fee charged by the platform; Positive number represents rebate
> fillFeeCcy	String	last filled fee currency or rebate currency. It is fee currency when fillFee is less than 0; It is rebate currency when fillFee>=0.
> fillPxVol	String	Implied volatility when filled Only applicable to options; return "" for other instrument types
> fillPxUsd	String	Options price when filled, in the unit of USD Only applicable to options; return "" for other instrument types
> fillMarkVol	String	Mark volatility when filled Only applicable to options; return "" for other instrument types
> fillFwdPx	String	Forward price when filled Only applicable to options; return "" for other instrument types
> fillMarkPx	String	Mark price when filled Applicable to `FUTURES`, `SWAP`, `OPTION`
> execType	String	Liquidity taker or maker of the last filled, T: taker M: maker
> accFillSz	String	Accumulated fill quantity The unit is `base_ccy` for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`; The unit is contract for `FUTURES`/`SWAP`/`OPTION`
> fillNotionalUsd	String	Filled notional value in `USD` of order
> avgPx	String	Average filled price. If none is filled, it will return `0`.
> state	String	Order state `canceled` `live` `partially_filled` `filled` `mmp_canceled`
> lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL.
> tpTriggerPx	String	Take-profit trigger price, it
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price, it
> slTriggerPx	String	Stop-loss trigger price, it
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price, it
> attachAlgoOrds	Array of object	TP/SL information attached when placing order
>> attachAlgoId	String	The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
>> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to `algoClOrdId` when placing TP/SL order once the general order is filled completely.
>> tpTriggerPx	String	Take-profit trigger price.
>> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
>> tpOrdPx	String	Take-profit order price.
>> slTriggerPx	String	Stop-loss trigger price.
>> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
>> slOrdPx	String	Stop-loss order price.
>> sz	String	Size. Only applicable to TP order of split TPs
>> amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
> stpId	String	Self trade prevention ID Return "" if self trade prevention is not applicable (deprecated)
> stpMode	String	Self trade prevention mode Return "" if self trade prevention is not applicable
> feeCcy	String	Fee currency `SPOT`/`MARGIN`: If you buy, you will receive `base currency`; if you sell, you will receive `quote currency`. `FUTURES`/`SWAP`/`OPTION` What is charged is the margin
> fee	String	Fee and rebate For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01. For Expiry Futures, Perpetual Futures and Options, it is accumulated fee and rebate
> rebateCcy	String	Rebate currency, if there is no rebate, this field is "".
> rebate	String	Rebate accumulated amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
> pnl	String	Profit and loss, applicable to orders which have a trade and aim to close position. It always is 0 in other conditions. For liquidation under cross margin mode, it will include liquidation penalties.
> source	String	Order source `6`: The normal order triggered by the `trigger order` `7`:The normal order triggered by the `TP/SL order` `13`: The normal order triggered by the algo order `25`:The normal order triggered by the `trailing stop order`
> cancelSource	String	Source of the order cancellation. Valid values and the corresponding meanings are: `0`: Order canceled by system `1`: Order canceled by user `2`: Order canceled: Pre reduce-only order canceled, due to insufficient margin in user position `3`: Order canceled: Risk cancellation was triggered. Pending order was canceled due to insufficient margin ratio and forced-liquidation risk. `4`: Order canceled: Borrowings of crypto reached hard cap, order was canceled by system. `6`: Order canceled: ADL order cancellation was triggered. Pending order was canceled due to a low margin ratio and forced-liquidation risk. `7`: Order canceled: Futures contract delivery. `9`: Order canceled: Insufficient balance after funding fees deducted. `13`: Order canceled: FOK order was canceled due to incompletely filled. `14`: Order canceled: IOC order was partially canceled due to incompletely filled. `15`: Order canceled: The order price is beyond the limit `17`: Order canceled: Close order was canceled, due to the position was already closed at market price. `20`: Cancel all after triggered `21`: Order canceled: The TP/SL order was canceled because the position had been closed `22`, `23`: Order canceled: Reduce-only orders only allow reducing your current position. System has already canceled this order. `27`: Order canceled: Price limit verification failed because the price difference between counterparties exceeds 5% `31`: The post-only order will take liquidity in taker orders `32`: Self trade prevention `33`: The order exceeds the maximum number of order matches per taker order
> amendSource	String	Source of the order amendation. `1`: Order amended by user `2`: Order amended by user, but the order quantity is overriden by system due to reduce-only `3`: New order placed by user, but the order quantity is overriden by system due to reduce-only `4`: Order amended by system due to other pending orders `5`: Order modification due to changes in options px, pxVol, or pxUsd as a result of following variations. For example, when iv = 60, USD and px are anchored at iv = 60, the changes in USD or px lead to modification.
> category	String	Category `normal` `twap` `adl` `full_liquidation` `partial_liquidation` `delivery` `ddh`: Delta dynamic hedge
> uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> reqId	String	Client Request ID as assigned by the client for order amendment. "" will be returned if there is no order amendment.
> amendResult	String	The result of amending the order `-1`: failure `0`: success `1`: Automatic cancel (amendment request returned success but amendment subsequently failed then automatically canceled by the system) `2`: Automatic amendation successfully, only applicable to pxVol and pxUsd orders of Option. When amending the order through API and `cxlOnFail` is set to `true` in the order amendment request but the amendment is rejected, "" is returned. When amending the order through API, the order amendment acknowledgement returns success and the amendment subsequently failed, `-1` will be returned if `cxlOnFail` is set to `false`, `1` will be returned if `cxlOnFail` is set to `true`. When amending the order through Web/APP and the amendment failed, `-1` will be returned.
> reduceOnly	String	Whether the order can only reduce the position size. Valid options: `true` or `false`.
> quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
> algoClOrdId	String	Client-supplied Algo ID. There will be a value when algo order attaching `algoClOrdId` is triggered, or it will be "".
> algoId	String	Algo ID. There will be a value when algo order is triggered, or it will be "".
> lastPx	String	Last price
> code	String	Error Code, the default is 0
> msg	String	Error Message, The default is ""

WS / Place order

You can place an order only if you have sufficient funds.

URL Path

/ws/v5/private (required login)

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1512",
  "op": "order",
  "args": [
    {
      "side": "buy",
      "instId": "BTC-USDT",
      "tdMode": "cash",
      "ordType": "market",
      "sz": "100"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `order`
args	Array	Yes	Request parameters
> instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
> tdMode	String	Yes	Trade mode `cash`
> clOrdId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
> tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
> side	String	Yes	Order side `buy` `sell`
> ordType	String	Yes	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
> sz	String	Yes	Quantity to buy or sell.
> px	String	Conditional	Order price. Only applicable to `limit`,`post_only`,`fok`,`ioc`,`mmp`,`mmp_and_post_only` order.
> tgtCcy	String	No	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
> banAmend	Boolean	No	Whether to disallow the system from amending the size of the SPOT Market Order. Valid options: `true` or `false`. The default value is `false`. If `true`, system will not amend and reject the market order if user does not have sufficient funds. Only applicable to SPOT Market Orders
> stpId	String	No	Self trade prevention ID. Orders from the same master account with the same ID will be prevented from self trade. Numerical integers defined by user in the range of 1<= x<= 999999999 (deprecated)
> stpMode	String	No	Self trade prevention mode. Default to cancel maker `cancel_maker`,`cancel_taker`, `cancel_both` Cancel both does not support FOK.
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

Successful Response Example

{
  "id": "1512",
  "op": "order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "12345689",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1512",
  "op": "order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "",
      "tag": "",
      "sCode": "5XXXX",
      "sMsg": "not exist"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1512",
  "op": "order",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> sCode	String	Order status code, `0` means success
> sMsg	String	Rejection or success message of event execution.
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

WS / Place multiple orders

Place orders in a batch. Maximum 20 orders can be placed per request

URL Path

/ws/v5/private (required login)

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1513",
  "op": "batch-orders",
  "args": [
    {
      "side": "buy",
      "instId": "BTC-USDT",
      "tdMode": "cash",
      "ordType": "market",
      "sz": "100"
    },
    {
      "side": "buy",
      "instId": "LTC-USDT",
      "tdMode": "cash",
      "ordType": "market",
      "sz": "1"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `batch-orders`
args	Array	Yes	Request Parameters
> instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
> tdMode	String	Yes	Trade mode `cash`
> clOrdId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
> tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
> side	String	Yes	Order side `buy` `sell`
> ordType	String	Yes	Order type `market`: market order `limit`: limit order `post_only`: Post-only order `fok`: Fill-or-kill order `ioc`: Immediate-or-cancel order
> sz	String	Yes	Quantity to buy or sell.
> px	String	Conditional	Order price. Only applicable to `limit`,`post_only`,`fok`,`ioc`,`mmp`,`mmp_and_post_only` order.
> tgtCcy	String	No	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
> banAmend	Boolean	No	Whether to disallow the system from amending the size of the SPOT Market Order. Valid options: `true` or `false`. The default value is `false`. If `true`, system will not amend and reject the market order if user does not have sufficient funds. Only applicable to SPOT Market Orders
> stpId	String	No	Self trade prevention ID. Orders from the same master account with the same ID will be prevented from self trade. Numerical integers defined by user in the range of 1<= x<= 999999999 (deprecated)
> stpMode	String	No	Self trade prevention mode. Default to cancel maker `cancel_maker`,`cancel_taker`, `cancel_both` Cancel both does not support FOK.
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

Response Example When All Succeed

{
  "id": "1513",
  "op": "batch-orders",
  "data": [
    {
      "clOrdId": "",
      "ordId": "12345689",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "",
      "ordId": "12344",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Partially Successful

{
  "id": "1513",
  "op": "batch-orders",
  "data": [
    {
      "clOrdId": "",
      "ordId": "12345689",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "",
      "ordId": "",
      "tag": "",
      "sCode": "5XXXX",
      "sMsg": "Insufficient margin"
    }
  ],
  "code": "2",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When All Failed

{
  "id": "1513",
  "op": "batch-orders",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "",
      "tag": "",
      "sCode": "5XXXX",
      "sMsg": "Insufficient margin"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "tag": "",
      "sCode": "5XXXX",
      "sMsg": "Insufficient margin"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1513",
  "op": "batch-orders",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> sCode	String	Order status code, `0` means success
> sMsg	String	Rejection or success message of event execution.
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

WS / Cancel order

Cancel an incomplete order

URL Path

/ws/v5/private (required login)

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1514",
  "op": "cancel-order",
  "args": [
    {
      "instId": "BTC-USDT",
      "ordId": "2510789768709120"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `cancel-order`
args	Array	Yes	Request Parameters
> instId	String	Yes	Instrument ID
> ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required, if both are passed, ordId will be used
> clOrdId	String	Conditional	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Successful Response Example

{
  "id": "1514",
  "op": "cancel-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1514",
  "op": "cancel-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "sCode": "5XXXX",
      "sMsg": "Order not exist"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1514",
  "op": "cancel-order",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> sCode	String	Order status code, `0` means success
> sMsg	String	Order status message
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

WS / Cancel multiple orders

Cancel incomplete orders in batches. Maximum 20 orders can be canceled per request.

URL Path

/ws/v5/private (required login)

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1515",
  "op": "batch-cancel-orders",
  "args": [
    {
      "instId": "BTC-USDT",
      "ordId": "2517748157541376"
    },
    {
      "instId": "LTC-USDT",
      "ordId": "2517748155771904"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `batch-cancel-orders`
args	Array	Yes	Request Parameters
> instId	String	Yes	Instrument ID
> ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required, if both are passed, ordId will be used
> clOrdId	String	Conditional	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Response Example When All Succeed

{
  "id": "1515",
  "op": "batch-cancel-orders",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "2517748157541376",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When partially successfully

{
  "id": "1515",
  "op": "batch-cancel-orders",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "2517748157541376",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "2",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When All Failed

{
  "id": "1515",
  "op": "batch-cancel-orders",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "2517748157541376",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1515",
  "op": "batch-cancel-orders",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> sCode	String	Order status code, `0` means success
> sMsg	String	Order status message
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

WS / Amend order

Amend an incomplete order.

URL Path

/ws/v5/private (required login)

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1512",
  "op": "amend-order",
  "args": [
    {
      "instId": "BTC-USDT",
      "ordId": "2510789768709120",
      "newSz": "2"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `amend-order`
args	Array	Yes	Request Parameters
> instId	String	Yes	Instrument ID
> cxlOnFail	Boolean	No	Whether the order needs to be automatically canceled when the order amendment fails Valid options: false or true, the default is false.
> ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required, if both are passed, `ordId` will be used.
> clOrdId	String	Conditional	Client Order ID as assigned by the client
> reqId	String	No	Client Request ID as assigned by the client for order amendment A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
> newSz	String	Conditional	New quantity after amendment. Either `newSz` or `newPx` is required. When amending a partially-filled order, the `newSz` should include the amount that has been filled.
> newPx	String	Conditional	New price after amendment.
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

Successful Response Example

{
  "id": "1512",
  "op": "amend-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1512",
  "op": "amend-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1512",
  "op": "amend-order",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> reqId	String	Client Request ID as assigned by the client for order amendment
> sCode	String	Order status code, `0` means success
> sMsg	String	Order status message
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

WS / Amend multiple orders

Amend incomplete orders in batches. Maximum 20 orders can be amended per request.

URL Path

/ws/v5/private (required login)

Rate Limit: 300 orders per 2 seconds

Rate limit rule: UserID + Instrument ID

Request Example

{
  "id": "1513",
  "op": "batch-amend-orders",
  "args": [
    {
      "instId": "BTC-USDT",
      "ordId": "12345689",
      "newSz": "2"
    },
    {
      "instId": "BTC-USDT",
      "ordId": "12344",
      "newSz": "2"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
id	String	Yes	Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op	String	Yes	Operation `batch-amend-orders`
args	Array	Yes	Request Parameters
> instId	String	Yes	Instrument ID
> cxlOnFail	Boolean	No	Whether the order needs to be automatically canceled when the order amendment fails Valid options: `false` or `true`, the default is `false`.
> ordId	String	Conditional	Order ID Either `ordId` or `clOrdId` is required, if both are passed, `ordId` will be used.
> clOrdId	String	Conditional	Client Order ID as assigned by the client
> reqId	String	No	Client Request ID as assigned by the client for order amendment A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
> newSz	String	Conditional	New quantity after amendment. Either `newSz` or `newPx` is required. When amending a partially-filled order, the `newSz` should include the amount that has been filled.
> newPx	String	Conditional	New price after amendment.
expTime	String	No	Request effective deadline. Unix timestamp format in milliseconds, e.g. `1597026383085`

Response Example When All Succeed

{
  "id": "1513",
  "op": "batch-amend-orders",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "12345689",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "12344",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When All Failed

{
  "id": "1513",
  "op": "batch-amend-orders",
  "data": [
    {
      "clOrdId": "",
      "ordId": "12345689",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "1",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Partially Successful

{
  "id": "1513",
  "op": "batch-amend-orders",
  "data": [
    {
      "clOrdId": "",
      "ordId": "12345689",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    }
  ],
  "code": "2",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Example When Format Error

{
  "id": "1513",
  "op": "batch-amend-orders",
  "data": [],
  "code": "60013",
  "msg": "Invalid args",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Response Parameters

Parameter	Type	Description
id	String	Unique identifier of the message
op	String	Operation
code	String	Error Code
msg	String	Error message
data	Array	Data
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> reqId	String	Client Request ID as assigned by the client for order amendment If the user provides reqId in the request, the corresponding reqId will be returned
> sCode	String	Order status code, `0` means success
> sMsg	String	Order status message
inTime	String	Timestamp at Websocket gateway when the request is received, Unix timestamp format in microseconds, e.g. `1597026383085123`
outTime	String	Timestamp at Websocket gateway when the response is sent, Unix timestamp format in microseconds, e.g. `1597026383085123`

Algo Trading

POST / Place algo order

The algo order includes trigger order, oco order, conditional order and trailing order.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/order-algo

Request Example

# Place Take Profit / Stop Loss Order
POST /api/v5/trade/order-algo
body
{
    "instId":"BTC-USDT",
    "tdMode":"cash",
    "side":"buy",
    "ordType":"conditional",
    "sz":"2",
    "tpTriggerPx":"15",
    "tpOrdPx":"18"
}

# Place Trigger Order
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT",
    "tdMode": "cash",
    "side": "buy",
    "ordType": "trigger",
    "sz": "10",
    "triggerPx": "100",
    "orderPx": "-1"
}

# Place Trailing Stop Order
POST /api/v5/trade/order-algo
body
{
    "instId": "BTC-USDT",
    "tdMode": "cash",
    "side": "buy",
    "ordType": "move_order_stop",
    "sz": "10",
    "callbackRatio": "0.05"
}

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# One-way stop order
result = tradeAPI.place_algo_order(
    instId="BTC-USDT",
    tdMode="cash",
    side="buy",
    ordType="conditional",
    sz="2",
    tpTriggerPx="15",
    tpOrdPx="18"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
tdMode	String	Yes	Trade mode `cash`
side	String	Yes	Order side `buy` `sell`
ordType	String	Yes	Order type `conditional`: One-way stop order `oco`: One-cancels-the-other order `trigger`: Trigger order `move_order_stop`: Trailing order
sz	String	Yes	Quantity to buy or sell
tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
tgtCcy	String	No	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` traded with Market buy `conditional` order Default is `quote_ccy` for buy, `base_ccy` for sell
algoClOrdId	String	No	Client-supplied Algo ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Take Profit / Stop Loss Order

learn more about Take Profit / Stop Loss Order

Parameter	Type	Required	Description
tpTriggerPx	String	No	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
tpTriggerPxType	String	No	Take-profit trigger price type `last`: last price The default is `last`
tpOrdPx	String	No	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is `-1`, take-profit will be executed at the market price.
slTriggerPx	String	No	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
slTriggerPxType	String	No	Stop-loss trigger price type `last`: last price The default is `last`
slOrdPx	String	No	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is `-1`, stop-loss will be executed at the market price.

Trigger Order

learn more about Trigger Order

Parameter	Type	Required	Description
triggerPx	String	Yes	Trigger price
orderPx	String	Yes	Order Price If the price is `-1`, the order will be executed at the market price.
triggerPxType	String	No	Trigger price type `last`: last price The default is `last`

Trailing Stop Order

learn more about Trailing Stop Order

Parameter	Type	Required	Description
callbackRatio	String	Conditional	Callback price ratio, e.g. `0.01` represents `1%` Either `callbackRatio` or `callbackSpread` is allowed to be passed.
callbackSpread	String	Conditional	Callback price variance
activePx	String	No	Active price The system will only start tracking the market and calculating your trigger price after the activation price is reached. If you don’t set a price, your order will be activated as soon as it’s placed.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "algoId": "12345689",
      "clOrdId": "",
      "algoClOrdId": "",
      "sCode": "0",
      "sMsg": ""
    }
  ]
}

Response Parameters

Parameter	Type	Description
algoId	String	Algo ID
clOrdId	String	~~Client Order ID as assigned by the client~~(Deprecated)
algoClOrdId	String	Client-supplied Algo ID
sCode	String	The code of the event execution result, `0` means success.
sMsg	String	Rejection message if the request is unsuccessful.

POST / Cancel algo order

Cancel unfilled algo orders. A maximum of 10 orders can be canceled per request. Request parameters should be passed in the form of an array.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID + instrumentID

HTTP Request

POST /api/v5/trade/cancel-algos

Request Example

POST /api/v5/trade/cancel-algos
body
[
    {
        "algoId":"198273485",
        "instId":"BTC-USDT"
    },
    {
        "algoId":"198273485",
        "instId":"BTC-USDT"
    }
]

Request Parameters

Parameter	Type	Required	Description
algoId	String	Yes	Algo ID
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoId":"1234",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Response Parameters

Parameter	Type	Description
algoId	String	Order ID
sCode	String	The code of the event execution result, `0` means success.
sMsg	String	Rejection message if the request is unsuccessful.

POST / Amend algo order

Amend unfilled algo orders (Support Stop order and Trigger order only, not including Move_order_stop order, Iceberg order, TWAP order, Trailing Stop order).

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID + Instrument ID

HTTP Request

POST /api/v5/trade/amend-algos

Request Example

POST /api/v5/trade/amend-algos
body
{
    "algoId":"2510789768709120",
    "newSz":"2",
    "instId":"BTC-USDT"
}

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID
algoId	String	Conditional	Algo ID Either `algoId` or `algoClOrdId` is required. If both are passed, `algoId` will be used.
algoClOrdId	String	Conditional	Client-supplied Algo ID Either `algoId` or `algoClOrdId` is required. If both are passed, `algoId` will be used.
cxlOnFail	Boolean	No	Whether the order needs to be automatically canceled when the order amendment fails Valid options: `false` or `true`, the default is `false`.
reqId	String	Conditional	Client Request ID as assigned by the client for order amendment A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. The response will include the corresponding `reqId` to help you identify the request if you provide it in the request.
newSz	String	Conditional	New quantity after amendment and it has to be larger than 0.

Take Profit / Stop Loss Order

Parameter	Type	Required	Description
newTpTriggerPx	String	Conditional	Take-profit trigger price. Either the take-profit trigger price or order price is 0, it means that the take-profit is deleted
newTpOrdPx	String	Conditional	Take-profit order price If the price is -1, take-profit will be executed at the market price.
newSlTriggerPx	String	Conditional	Stop-loss trigger price. Either the stop-loss trigger price or order price is 0, it means that the stop-loss is deleted
newSlOrdPx	String	Conditional	Stop-loss order price If the price is -1, stop-loss will be executed at the market price.
newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price
newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "algoClOrdId":"algo_01",
            "algoId":"2510789768709120",
            "reqId":"po103ux",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Response Parameters

Parameter	Type	Description
algoId	String	Algo ID
algoClOrdId	String	Client-supplied Algo ID
reqId	String	Client Request ID as assigned by the client for order amendment.
sCode	String	The code of the event execution result, `0` means success.
sMsg	String	Rejection message if the request is unsuccessful.

GET / Algo order details

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/order-algo

Request Example

GET /api/v5/trade/order-algo?algoId=1753184812254216192

Request Parameters

Parameter	Type	Required	Description
algoId	String	Conditional	Algo ID Either `algoId` or `algoClOrdId` is required.If both are passed, `algoId` will be used.
algoClOrdId	String	Conditional	Client-supplied Algo ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Response Example

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "",
            "actualSz": "",
            "algoClOrdId": "",
            "algoId": "681187161907138560",
            "amendPxOnTriggerType": "",
            "attachAlgoOrds": [],
            "cTime": "1708679675244",
            "uTime": "1708679675245",
            "callbackRatio": "0.05",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "last": "50962.7",
            "lever": "",
            "linkedOrd": {
                "ordId": ""
            },
            "moveTriggerPx": "53423.160",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "",
            "ordType": "move_order_stop",
            "posSide": "net",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "live",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "",
            "triggerPxType": "",
            "triggerTime": "",
            "isTradeBorrowMode": "true"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Latest order ID. It will be deprecated soon
ordIdList	Array	Order ID list. There will be multiple order IDs when there is TP/SL splitting order.
algoId	String	Algo ID
clOrdId	String	Client Order ID as assigned by the client
sz	String	Quantity to buy or sell
closeFraction	String	Fraction of position to be closed when the algo order is triggered
ordType	String	Order type
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
state	String	State `live` `pause` `partially_effective` `effective` `canceled` `order_failed` `partially_failed`
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
triggerPx	String	trigger price.
triggerPxType	String	trigger price type. `last`: last price `index`: index price `mark`: mark price
ordPx	String	Order price for the trigger order
actualSz	String	Actual order quantity
actualPx	String	Actual order price
tag	String	Order tag
actualSide	String	Actual trigger side, `tp`: take profit `sl`: stop loss Only applicable to oco order and conditional order
triggerTime	String	Trigger time, Unix timestamp format in milliseconds, e.g. `1597026383085`
pxVar	String	Price ratio Only applicable to `iceberg` order or `twap` order
pxSpread	String	Price variance Only applicable to `iceberg` order or `twap` order
szLimit	String	Average amount Only applicable to `iceberg` order or `twap` order
pxLimit	String	Price Limit Only applicable to `iceberg` order or `twap` order
timeInterval	String	Time interval Only applicable to `twap` order
callbackRatio	String	Callback price ratio Only applicable to `move_order_stop` order
callbackSpread	String	Callback price variance Only applicable to `move_order_stop` order
activePx	String	Active price Only applicable to `move_order_stop` order
moveTriggerPx	String	Trigger price Only applicable to `move_order_stop` order
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
last	String	Last filled price while placing
failCode	String	It represents that the reason that algo order fails to trigger. It is "" when the state is `effective`/`canceled`. There will be value when the state is `order_failed`, e.g. 51008; Only applicable to Stop Order, Trailing Stop Order, Trigger order.
algoClOrdId	String	Client-supplied Algo ID
amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
attachAlgoOrds	Array of object	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to algoClOrdId when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
> tpTriggerPxType	String	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is `-1`, take-profit will be executed at the market price.
> slTriggerPx	String	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
> slTriggerPxType	String	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is `-1`, stop-loss will be executed at the market price.
linkedOrd	Object	Linked TP order detail, only applicable to SL order that comes from the one-cancels-the-other (OCO) order that contains the TP limit order.
> ordId	String	Order ID
cTime	String	Creation time Unix timestamp format in milliseconds, e.g. `1597026383085`
uTime	String	Order updated time, Unix timestamp format in milliseconds, e.g. 1597026383085
isTradeBorrowMode	String	是否自动借币 true：自动借币 false：不自动借币仅适用于计划委托、移动止盈止损和时间加权策略

GET / Algo order list

Retrieve a list of untriggered Algo orders under the current account.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-algo-pending

Request Example

GET /api/v5/trade/orders-algo-pending?ordType=conditional

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve a list of untriggered one-way stop orders
result = tradeAPI.order_algos_list(
    ordType="conditional"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ordType	String	Yes	Order type `conditional`: One-way stop order `oco`: One-cancels-the-other order `trigger`: Trigger order `move_order_stop`: Trailing order
algoId	String	No	Algo ID
algoClOrdId	String	No	Client-supplied Algo ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
instType	String	No	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
after	String	No	Pagination of data to return records earlier than the requested `algoId`.
before	String	No	Pagination of data to return records newer than the requested `algoId`.
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "buy",
            "actualSz": "0",
            "algoClOrdId": "",
            "algoId": "681096944655273984",
            "amendPxOnTriggerType": "",
            "attachAlgoOrds": [],
            "cTime": "1708658165774",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "last": "51014.6",
            "lever": "",
            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "-1",
            "ordType": "trigger",
            "posSide": "net",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "live",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "100",
            "triggerPxType": "last",
            "triggerTime": "0"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Latest order ID
ordIdList	Array	Order ID list. There will be multiple order IDs when there is TP/SL splitting order.
algoId	String	Algo ID
clOrdId	String	Client Order ID as assigned by the client
sz	String	Quantity to buy or sell
closeFraction	String	Fraction of position to be closed when the algo order is triggered
ordType	String	Order type
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` traded with Market order
state	String	State,`live` `pause`
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
tpTriggerPx	String	Take-profit trigger price
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price
slTriggerPx	String	Stop-loss trigger price
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price
triggerPx	String	Trigger price
triggerPxType	String	Trigger price type `last`: last price `index`: index price `mark`: mark price
ordPx	String	Order price for the trigger order
actualSz	String	Actual order quantity
tag	String	Order tag
actualPx	String	Actual order price
actualSide	String	Actual trigger side `tp`: take profit `sl`: stop loss Only applicable to oco order and conditional order
triggerTime	String	Trigger time, Unix timestamp format in milliseconds, e.g. `1597026383085`
pxVar	String	Price ratio Only applicable to `iceberg` order or `twap` order
pxSpread	String	Price variance Only applicable to `iceberg` order or `twap` order
szLimit	String	Average amount Only applicable to `iceberg` order or `twap` order
pxLimit	String	Price Limit Only applicable to `iceberg` order or `twap` order
timeInterval	String	Time interval Only applicable to `twap` order
callbackRatio	String	Callback price ratio Only applicable to `move_order_stop` order
callbackSpread	String	Callback price variance Only applicable to `move_order_stop` order
activePx	String	Active price Only applicable to `move_order_stop` order
moveTriggerPx	String	Trigger price Only applicable to `move_order_stop` order
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
last	String	Last filled price while placing
failCode	String	It represents that the reason that algo order fails to trigger. There will be value when the state is `order_failed`, e.g. 51008; For this endpoint, it always is "".
algoClOrdId	String	Client-supplied Algo ID
amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
attachAlgoOrds	Array of object	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to algoClOrdId when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
> tpTriggerPxType	String	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
> tpOrdPx	String	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is `-1`, take-profit will be executed at the market price.
> slTriggerPx	String	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
> slTriggerPxType	String	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
> slOrdPx	String	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is `-1`, stop-loss will be executed at the market price.
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET / Algo order history

Retrieve a list of all algo orders under the current account in the last 3 months.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-algo-history

Request Example

GET /api/v5/trade/orders-algo-history?ordType=conditional&state=effective

import okx.Trade as Trade

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

tradeAPI = Trade.TradeAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve a list of all one-way stop algo orders
result = tradeAPI.order_algos_history(
    state="effective",
    ordType="conditional"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ordType	String	Yes	Order type `conditional`: One-way stop order `oco`: One-cancels-the-other order `trigger`: Trigger order `move_order_stop`: Trailing order
state	String	Conditional	State `effective` `canceled` `order_failed` Either `state` or `algoId` is required
algoId	String	Conditional	Algo ID Either `state` or `algoId` is required.
instType	String	No	Instrument type `SPOT`
instId	String	No	Instrument ID, e.g. `BTC-USDT`
after	String	No	Pagination of data to return records earlier than the requested `algoId`
before	String	No	Pagination of data to return records new than the requested `algoId`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`

Response Example

{
    "code": "0",
    "data": [
        {
            "activePx": "",
            "actualPx": "",
            "actualSide": "buy",
            "actualSz": "0",
            "algoClOrdId": "",
            "algoId": "681096944655273984",
            "amendPxOnTriggerType": "",
            "attachAlgoOrds": [],
            "cTime": "1708658165774",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "last": "51014.6",
            "lever": "",
            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "-1",
            "ordType": "trigger",
            "posSide": "net",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "quickMgnType": "",
            "reduceOnly": "false",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "canceled",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "100",
            "triggerPxType": "last",
            "triggerTime": ""
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
ccy	String	Margin currency Only applicable to `cross` `MARGIN` orders in `Spot and futures mode`.
ordId	String	Latest order ID
ordIdList	Array	Order ID list. There will be multiple order IDs when there is TP/SL splitting order.
algoId	String	Algo ID
clOrdId	String	Client Order ID as assigned by the client
sz	String	Quantity to buy or sell
closeFraction	String	Fraction of position to be closed when the algo order is triggered
ordType	String	Order type
side	String	Order side
posSide	String	Position side
tdMode	String	Trade mode
tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
state	String	State `effective` `canceled` `order_failed` `partially_failed`
lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price `index`: index price `mark`: mark price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price `index`: index price `mark`: mark price
slOrdPx	String	Stop-loss order price.
triggerPx	String	trigger price.
triggerPxType	String	trigger price type. `last`: last price `index`: index price `mark`: mark price
ordPx	String	Order price for the trigger order
actualSz	String	Actual order quantity
actualPx	String	Actual order price
tag	String	Order tag
actualSide	String	Actual trigger side, `tp`: take profit `sl`: stop loss Only applicable to oco order and conditional order
triggerTime	String	Trigger time, Unix timestamp format in milliseconds, e.g. `1597026383085`
pxVar	String	Price ratio Only applicable to `iceberg` order or `twap` order
pxSpread	String	Price variance Only applicable to `iceberg` order or `twap` order
szLimit	String	Average amount Only applicable to `iceberg` order or `twap` order
pxLimit	String	Price Limit Only applicable to `iceberg` order or `twap` order
timeInterval	String	Time interval Only applicable to `twap` order
callbackRatio	String	Callback price ratio Only applicable to `move_order_stop` order
callbackSpread	String	Callback price variance Only applicable to `move_order_stop` order
activePx	String	Active price Only applicable to `move_order_stop` order
moveTriggerPx	String	Trigger price Only applicable to `move_order_stop` order
reduceOnly	String	Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType	String	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
last	String	Last filled price while placing
failCode	String	It represents that the reason that algo order fails to trigger. It is "" when the state is `effective`/`canceled`. There will be value when the state is `order_failed`, e.g. 51008; Only applicable to Stop Order, Trailing Stop Order, Trigger order.
algoClOrdId	String	Client Algo Order ID as assigned by the client.
amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
attachAlgoOrds	Array of object	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to algoClOrdId when placing TP/SL order once the general order is filled completely.
> tpTriggerPx	String	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
> tpTriggerPxType	String	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
> tpOrdPx	String	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is `-1`, take-profit will be executed at the market price.
> slTriggerPx	String	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
> slTriggerPxType	String	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
> slOrdPx	String	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is `-1`, stop-loss will be executed at the market price.
cTime	String	Creation time Unix timestamp format in milliseconds, e.g. `1597026383085`

WS / Algo orders channel

Retrieve algo orders (includes trigger order, oco order, conditional order). Data will not be pushed when first subscribed. Data will only be pushed when there are order updates.

URL Path

/ws/v5/business (required login)

Request Example : single

{
  "op": "subscribe",
  "args": [
    {
      "channel": "orders-algo",
      "instType": "ANY"
    }
  ]
}

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "orders-algo",
      "instType": "ANY"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `orders-algo`
> instType	String	Yes	Instrument type `ANY`
> instId	String	No	Instrument ID

Successful Response Example : single

{
  "event": "subscribe",
  "arg": {
    "channel": "orders-algo",
    "instType": "ANY"
  },
  "connId": "a4d3ae55"
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders-algo",
    "instType": "ANY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders-algo\", \"instType\" : \"FUTURES\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instType	String	Yes	Instrument type `ANY`
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example: single

{
    "arg": {
        "channel": "orders-algo",
        "uid": "77982378738415879",
        "instType": "ANY"
    },
    "data": [{
        "actualPx": "0",
        "actualSide": "",
        "actualSz": "0",
        "algoClOrdId": "",
        "algoId": "581878926302093312",
        "attachAlgoOrds": [],
        "amendResult": "",
        "cTime": "1685002746818",
        "ccy": "",
        "clOrdId": "",
        "closeFraction": "",
        "failCode": "",
        "instId": "BTC-USDC",
        "instType": "SPOT",
        "last": "26174.8",
        "lever": "0",
        "notionalUsd": "11.0",
        "ordId": "",
        "ordIdList": [],
        "ordPx": "",
        "ordType": "conditional",
        "posSide": "",
        "quickMgnType": "",
        "reduceOnly": "false",
        "reqId": "",
        "side": "buy",
        "slOrdPx": "",
        "slTriggerPx": "",
        "slTriggerPxType": "",
        "state": "live",
        "sz": "11",
        "tag": "",
        "tdMode": "cross",
        "tgtCcy": "quote_ccy",
        "tpOrdPx": "-1",
        "tpTriggerPx": "1",
        "tpTriggerPxType": "last",
        "triggerPx": "",
        "triggerTime": "",
        "amendPxOnTriggerType": "0"
    }]
}

Response parameters when data is pushed.

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> uid	String	User Identifier
> instType	String	Instrument type
> instFamily	String	Instrument family
> instId	String	Instrument ID
data	Array	Subscribed data
> instType	String	Instrument type
> instId	String	Instrument ID
> ccy	String	Margin currency Only applicable to cross `MARGIN` orders in `Spot and futures mode`.
> ordId	String	Latest order ID, the order ID associated with the algo order.
> ordIdList	Array	Order ID list. There will be multiple order IDs when there is TP/SL splitting order.
> algoId	String	Algo ID
> clOrdId	String	Client Order ID as assigned by the client
> sz	String	Quantity to buy or sell. `SPOT`/`MARGIN`: in the unit of currency. `FUTURES`/`SWAP`/`OPTION`: in the unit of contract.
> ordType	String	Order type `conditional`: One-way stop order `oco`: One-cancels-the-other order `trigger`: Trigger order
> side	String	Order side `buy` `sell`
> posSide	String	Position side `net` `long` or `short` Only applicable to `FUTURES`/`SWAP`
> tdMode	String	Trade mode `cross`: cross `isolated`: isolated `cash`: cash
> tgtCcy	String	Order quantity unit setting for `sz` `base_ccy`: Base currency ,`quote_ccy`: Quote currency Only applicable to `SPOT` Market Orders Default is `quote_ccy` for buy, `base_ccy` for sell
> lever	String	Leverage, from `0.01` to `125`. Only applicable to `MARGIN/FUTURES/SWAP`
> state	String	Order status `live`: to be effective `effective`: effective `canceled`: canceled `order_failed`: order failed `partially_failed`: partially failed
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price
> slOrdPx	String	Stop-loss order price.
> triggerPx	String	Trigger price
> triggerPxType	String	Trigger price type. `last`: last price `index`: index price `mark`: mark price
> ordPx	String	Order price for the trigger order
> last	String	Last filled price while placing
> actualSz	String	Actual order quantity
> actualPx	String	Actual order price
> notionalUsd	String	Estimated national value in `USD` of order
> tag	String	Order tag
> actualSide	String	Actual trigger side Only applicable to oco order and conditional order
> triggerTime	String	Trigger time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> reduceOnly	String	Whether the order can only reduce the position size. Valid options: `true` or `false`.
> failCode	String	It represents that the reason that algo order fails to trigger. It is "" when the state is `effective`/`canceled`. There will be value when the state is `order_failed`, e.g. 51008; Only applicable to Stop Order, Trailing Stop Order, Trigger order.
> algoClOrdId	String	Client Algo Order ID as assigned by the client.
> cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> reqId	String	Client Request ID as assigned by the client for order amendment. "" will be returned if there is no order amendment.
> amendResult	String	The result of amending the order `-1`: failure `0`: success
> amendPxOnTriggerType	String	Whether to enable Cost-price SL. Only applicable to SL order of split TPs. `0`: disable, the default value `1`: Enable
> attachAlgoOrds	Array of object	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
>> attachAlgoClOrdId	String	Client-supplied Algo ID when placing order attaching TP/SL. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to algoClOrdId when placing TP/SL order once the general order is filled completely.
>> tpTriggerPx	String	Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well.
>> tpTriggerPxType	String	Take-profit trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
>> tpOrdPx	String	Take-profit order price If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is `-1`, take-profit will be executed at the market price.
>> slTriggerPx	String	Stop-loss trigger price If you fill in this parameter, you should fill in the stop-loss order price.
>> slTriggerPxType	String	Stop-loss trigger price type `last`: last price `index`: index price `mark`: mark price The default is `last`
>> slOrdPx	String	Stop-loss order price If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is `-1`, stop-loss will be executed at the market price.

Market Data

The API endpoints of Market Data do not require authentication.

GET / Tickers

Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/tickers

Request Example

GET /api/v5/market/tickers?instType=SPOT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours
result = marketDataAPI.get_tickers(
    instType="SPOT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument type `SPOT`

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "instType": "SPOT",
            "instId": "BTC-USDT",
            "last": "51230",
            "lastSz": "0.18531491",
            "askPx": "51229.4",
            "askSz": "2.1683067",
            "bidPx": "51229.3",
            "bidSz": "0.28249897",
            "open24h": "51635.7",
            "high24h": "52080",
            "low24h": "50936",
            "volCcy24h": "539658490.410419122",
            "vol24h": "10476.2229261",
            "ts": "1708669508505",
            "sodUtc0": "51290.1",
            "sodUtc8": "51602.4"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size
askPx	String	Best ask price
askSz	String	Best ask size
bidPx	String	Best bid price
bidSz	String	Best bid size
open24h	String	Open price in the past 24 hours
high24h	String	Highest price in the past 24 hours
low24h	String	Lowest price in the past 24 hours
volCcy24h	String	24h trading volume If it is `SPOT`, the value is the quantity in quote currency.
vol24h	String	24h trading volume If it is `SPOT`, the value is the quantity in base currency.
sodUtc0	String	Open price in the UTC 0
sodUtc8	String	Open price in the UTC 8
ts	String	Ticker data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET / Ticker

Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/ticker

Request Example

GET /api/v5/market/ticker?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours
result = marketDataAPI.get_ticker(
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instType": "SPOT",
            "instId": "BTC-USDT",
            "last": "51240",
            "lastSz": "0.49011124",
            "askPx": "51240",
            "askSz": "0.64278176",
            "bidPx": "51239.9",
            "bidSz": "1.68139044",
            "open24h": "51695.6",
            "high24h": "52080",
            "low24h": "50936",
            "volCcy24h": "539533972.680195094",
            "vol24h": "10474.12353007",
            "ts": "1708669925904",
            "sodUtc0": "51290.1",
            "sodUtc8": "51602.4"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size
askPx	String	Best ask price
askSz	String	Best ask size
bidPx	String	Best bid price
bidSz	String	Best bid size
open24h	String	Open price in the past 24 hours
high24h	String	Highest price in the past 24 hours
low24h	String	Lowest price in the past 24 hours
volCcy24h	String	24h trading volume If it is `SPOT`, the value is the quantity in quote currency.
vol24h	String	24h trading volume If it is `SPOT`, the value is the quantity in base currency.
sodUtc0	String	Open price in the UTC 0
sodUtc8	String	Open price in the UTC 8
ts	String	Ticker data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.

GET / Order book

Retrieve order book of the instrument.

Rate Limit: 40 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/books

Request Example

GET /api/v5/market/books?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve order book of the instrument
result = marketDataAPI.get_orderbook(
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
sz	String	No	Order book depth per side. Maximum 400, e.g. 400 bids + 400 asks Default returns to `1` depth data

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "0",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "0",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

Response Parameters

Parameter	Type	Description
asks	Array	Order book on sell side
bids	Array	Order book on buy side
ts	String	Order book generation time

GET / Candlesticks

Retrieve the candlestick charts. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.

Rate Limit: 40 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/candles

Request Example

GET /api/v5/market/candles?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve the candlestick charts
result = marketDataAPI.get_candlesticks(
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H] Hong Kong time opening price k-line: [6H/12H/1D/2D/3D/1W/1M/3M] UTC time opening price k-line: [/6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`. The latest data will be returned when using `before` individually
limit	String	No	Number of results per request. The maximum is `300`. The default is `100`.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "0"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Opening time of the candlestick, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	highest price
l	String	Lowest price
c	String	Close price
vol	String	Trading volume If it is `SPOT`, the value is the quantity in base currency.
volCcy	String	Trading volume If it is `SPOT`, the value is the quantity in quote currency.
volCcyQuote	String	Trading volume, the value is the quantity in quote currency e.g. The unit is `USDT` for `BTC-USDT`
confirm	String	The state of candlesticks. `0`: K line is uncompleted `1`: K line is completed

GET / Candlesticks history

Retrieve history candlestick charts from recent years(It is last 3 months supported for 1s candlestick).

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/history-candles

Request Example

GET /api/v5/market/history-candles?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve history candlestick charts from recent years
result = marketDataAPI.get_history_candlesticks(
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`. The latest data will be returned when using `before` individually
bar	String	No	Bar size, the default is `1m` e.g. [1s/1m/3m/5m/15m/30m/1H/2H/4H] Hong Kong time opening price k-line: [6H/12H/1D/2D/3D/1W/1M/3M] UTC time opening price k-line: [6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc]
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491",
        "12698348.04828491",
        "1"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722",
        "37632347.24399722",
        "1"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Opening time of the candlestick, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	Highest price
l	String	Lowest price
c	String	Close price
vol	String	Trading volume If it is `SPOT`, the value is the quantity in base currency.
volCcy	String	Trading volume If it is `SPOT`, the value is the quantity in quote currency.
volCcyQuote	String	Trading volume, the value is the quantity in quote currency e.g. The unit is `USDT` for `BTC-USDT`
confirm	String	The state of candlesticks. `0`: K line is uncompleted `1`: K line is completed

GET / Trades

Retrieve the recent transactions of an instrument.

Rate Limit: 100 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/trades

Request Example

GET /api/v5/market/trades?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve the recent transactions of an instrument
result = marketDataAPI.get_trades(
    instId="BTC-USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
limit	String	No	Number of results per request. The maximum is `500`; The default is `100`

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
tradeId	String	Trade ID
px	String	Trade price
sz	String	Trade quantity For spot trading, the unit is base currency
side	String	Trade side `buy` `sell`
ts	String	Trade time, Unix timestamp format in milliseconds, e.g. `1597026383085`.

GET / Trades history

Retrieve the recent transactions of an instrument from the last 3 months with pagination.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/history-trades

Request Example

GET /api/v5/market/history-trades?instId=BTC-USDT

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve the recent transactions of an instrument from the last 3 months with pagination
result = marketDataAPI.get_history_trades(
    instId="BTC-USD-SWAP"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USDT`
type	String	No	Pagination Type `1`: tradeId `2`: timestamp The default is `1`
after	String	No	Pagination of data to return records earlier than the requested tradeId or ts.
before	String	No	Pagination of data to return records newer than the requested tradeId. Do not support timestamp for pagination. The latest data will be returned when using `before` individually
limit	String	No	Number of results per request. The maximum and default both are `100`

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-USDT",
            "side": "sell",
            "sz": "0.00001",
            "px": "29964.1",
            "tradeId": "242720719",
            "ts": "1654161641568"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
tradeId	String	Trade ID
px	String	Trade price
sz	String	Trade quantity
side	String	Trade side `buy` `sell`
ts	String	Trade time, Unix timestamp format in milliseconds, e.g. `1597026383085`.

GET / 24H total volume

The 24-hour trading volume is calculated on a rolling basis.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/platform-24-volume

Request Example

GET /api/v5/market/platform-24-volume

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve 24 total volume
result = marketDataAPI.get_volume()
print(result)

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
     {
         "volCny": "230900886396766",
         "volUsd": "34462818865189",
         "ts": "1657856040389"
     }
  ]
}

Response Parameters

Parameter	Type	Description
volUsd	String	24-hour total trading volume from the order book trading in "USD"
volCny	String	24-hour total trading volume from the order book trading in "CNY"
ts	String	Data return time, Unix timestamp format in milliseconds, e.g. `1597026383085`

WS / Tickers channel

Retrieve the last traded price, bid price, ask price and 24-hour trading volume of instruments.
The fastest rate is 1 update/100ms. There will be no update if the event is not triggered. The events which can trigger update: trade, the change on best ask/bid.

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "tickers",
      "instId": "BTC-USDT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `tickers`
> instId	String	Yes	Instrument ID

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "tickers",
    "instId": "BTC-USDT"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"tickers\", \"instId\" : \"LTC-USD-200327\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
  "arg": {
    "channel": "tickers",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instType": "SPOT",
      "instId": "BTC-USDT",
      "last": "9999.99",
      "lastSz": "0.1",
      "askPx": "9999.99",
      "askSz": "11",
      "bidPx": "8888.88",
      "bidSz": "5",
      "open24h": "9000",
      "high24h": "10000",
      "low24h": "8888.88",
      "volCcy24h": "2222",
      "vol24h": "2222",
      "sodUtc0": "2222",
      "sodUtc8": "2222",
      "ts": "1597026383085"
    }
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> instId	String	Instrument ID
data	Array	Subscribed data
> instType	String	Instrument type
> instId	String	Instrument ID
> last	String	Last traded price
> lastSz	String	Last traded size
> askPx	String	Best ask price
> askSz	String	Best ask size
> bidPx	String	Best bid price
> bidSz	String	Best bid size
> open24h	String	Open price in the past 24 hours
> high24h	String	Highest price in the past 24 hours
> low24h	String	Lowest price in the past 24 hours
> volCcy24h	String	24h trading volume If it is `SPOT`, the value is the quantity in quote currency.
> vol24h	String	24h trading volume If it is `SPOT`, the value is the quantity in base currency.
> sodUtc0	String	Open price in the UTC 0
> sodUtc8	String	Open price in the UTC 8
> ts	String	Ticker data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

WS / Candlesticks channel

Retrieve the candlesticks data of an instrument. the push frequency is the fastest interval 1 second push the data.

URL Path

/ws/v5/business

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "candle1D",
      "instId": "BTC-USDT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `candle3M` `candle1M` `candle1W` `candle1D` `candle2D` `candle3D` `candle5D` `candle12H` `candle6H` `candle4H` `candle2H` `candle1H` `candle30m` `candle15m` `candle5m` `candle3m` `candle1m` `candle1s` `candle3Mutc` `candle1Mutc` `candle1Wutc` `candle1Dutc` `candle2Dutc` `candle3Dutc` `candle5Dutc` `candle12Hutc` `candle6Hutc`
> instId	String	Yes	Instrument ID

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "candle1D",
    "instId": "BTC-USDT"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"candle1D\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	yes	channel name
> instId	String	Yes	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
  "arg": {
    "channel": "candle1D",
    "instId": "BTC-USDT"
  },
  "data": [
    [
      "1597026383085",
      "8533.02",
      "8553.74",
      "8527.17",
      "8548.26",
      "45247",
      "529.5858061",
      "5529.5858061",
      "0"
    ]
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> instId	String	Instrument ID
data	Array	Subscribed data
> ts	String	Opening time of the candlestick, Unix timestamp format in milliseconds, e.g. `1597026383085`
> o	String	Open price
> h	String	highest price
> l	String	Lowest price
> c	String	Close price
> vol	String	Trading volume If it is `SPOT`, the value is the quantity in base currency.
> volCcy	String	Trading volume If it is `SPOT`, the value is the quantity in quote currency.
> volCcyQuote	String	Trading volume, the value is the quantity in quote currency e.g. The unit is `USDT` for `BTC-USDT`
> confirm	String	The state of candlesticks `0`: K line is uncompleted `1`: K line is completed

WS / Trades channel

Retrieve the recent trades data. Data will be pushed whenever there is a trade. Every update may aggregate multiple trades.

The message is sent only once per taker order, per filled price. The count field is used to represent the number of aggregated matches.

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "trades",
      "instId": "BTC-USDT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `trades`
> instId	String	Yes	Instrument ID

Successful Response Example

{
  "event": "subscribe",
  "arg": {
      "channel": "trades",
      "instId": "BTC-USDT"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
  "arg": {
    "channel": "trades",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897",
      "count": "3"
    }
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> instId	String	Instrument ID
data	Array	Subscribed data
> instId	String	Instrument ID, e.g. `BTC-USDT`
> tradeId	String	The last trade ID in the trades aggregation
> px	String	Trade price
> sz	String	Trade size
> side	String	Trade direction `buy` `sell`
> ts	String	Filled time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> count	String	The count of trades aggregated

Aggregation function description:
1. The system will send only one message per taker order, per filled price. The `count` field will be used to represent the number of aggregated matches.
2. The `tradeId` field in the message becomes the last trade ID in the aggregation.
3. When the `count` = 1, it means the taker order matches only one maker order with the specific price.
4. When the `count` > 1, it means the taker order matches multiple maker orders with the same price. For example, if `tradeId` = 123 and `count` = 3, it means the message aggregates the trades of `tradeId` = 123, 122, and 121. Maker side has filled multiple orders.
5. Users can use this information to compare with data from the `trades-all` channel.
6. Order book and the aggregated trades data are still published sequentially.

WS / All trades channel

Retrieve the recent trades data. Data will be pushed whenever there is a trade. Every update contain only one trade.

URL Path

/ws/v5/business

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "trades-all",
      "instId": "BTC-USDT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `trades-all`
> instId	String	Yes	Instrument ID

Successful Response Example

{
  "event": "subscribe",
  "arg": {
      "channel": "trades-all",
      "instId": "BTC-USDT"
    },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades-all\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
  "arg": {
    "channel": "trades-all",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897"
    }
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> instId	String	Instrument ID
data	Array	Subscribed data
> instId	String	Instrument ID, e.g. `BTC-USDT`
> tradeId	String	Trade ID
> px	String	Trade price
> sz	String	Trade size
> side	String	Trade direction `buy` `sell`
> ts	String	Filled time, Unix timestamp format in milliseconds, e.g. `1597026383085`

WS / Order book channel

Retrieve order book data.

Use books for 400 depth levels, books5 for 5 depth levels, bbo-tbt tick-by-tick 1 depth level, books50-l2-tbt tick-by-tick 50 depth levels, and books-l2-tbt for tick-by-tick 400 depth levels.

books: 400 depth levels will be pushed in the initial full snapshot. Incremental data will be pushed every 100 ms for the changes in the order book during that period of time.
books5: 5 depth levels snapshot will be pushed in the initial push. Snapshot data will be pushed every 100 ms when there are changes in the 5 depth levels snapshot.
bbo-tbt: 1 depth level snapshot will be pushed in the initial push. Snapshot data will be pushed every 10 ms when there are changes in the 1 depth level snapshot.
books-l2-tbt: 400 depth levels will be pushed in the initial full snapshot. Incremental data will be pushed every 10 ms for the changes in the order book during that period of time.
books50-l2-tbt: 50 depth levels will be pushed in the initial full snapshot. Incremental data will be pushed every 10 ms for the changes in the order book during that period of time.
The push sequence for order book channels within the same connection and trading symbols is fixed as: bbo-tbt -> books-l2-tbt -> books50-l2-tbt -> books -> books5.
Users can not simultaneously subscribe to books-l2-tbt and books50-l2-tbt/books channels for the same trading symbol.
- For more details, please refer to the changelog 2024-07-17

Identity verification refers to Login

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "books",
      "instId": "BTC-USDT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `books` `books5` `bbo-tbt` `books50-l2-tbt` `books-l2-tbt`
> instId	String	Yes	Instrument ID

Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "books",
    "instId": "BTC-USDT"
  },
  "connId": "a4d3ae55"
}

Failure example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"books\", \"instId\" : \"BTC-USD-191227\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID
msg	String	No	Error message
code	String	No	Error code
connId	String	Yes	WebSocket connection ID

Push Data Example: Full Snapshot

{
  "arg": {
    "channel": "books",
    "instId": "BTC-USDT"
  },
  "action": "snapshot",
  "data": [
    {
      "asks": [
        ["8476.98", "415", "0", "13"],
        ["8477", "7", "0", "2"],
        ["8477.34", "85", "0", "1"],
        ["8477.56", "1", "0", "1"],
        ["8505.84", "8", "0", "1"],
        ["8506.37", "85", "0", "1"],
        ["8506.49", "2", "0", "1"],
        ["8506.96", "100", "0", "2"]
      ],
      "bids": [
        ["8476.97", "256", "0", "12"],
        ["8475.55", "101", "0", "1"],
        ["8475.54", "100", "0", "1"],
        ["8475.3", "1", "0", "1"],
        ["8447.32", "6", "0", "1"],
        ["8447.02", "246", "0", "1"],
        ["8446.83", "24", "0", "1"],
        ["8446", "95", "0", "3"]
      ],
      "ts": "1597026383085",
      "checksum": -855196043,
      "prevSeqId": -1,
      "seqId": 123456
    }
  ]
}

Push Data Example: Incremental Data

{
  "arg": {
    "channel": "books",
    "instId": "BTC-USDT"
  },
  "action": "update",
  "data": [
    {
      "asks": [
        ["8476.98", "415", "0", "13"],
        ["8477", "7", "0", "2"],
        ["8477.34", "85", "0", "1"],
        ["8477.56", "1", "0", "1"],
        ["8505.84", "8", "0", "1"],
        ["8506.37", "85", "0", "1"],
        ["8506.49", "2", "0", "1"],
        ["8506.96", "100", "0", "2"]
      ],
      "bids": [
        ["8476.97", "256", "0", "12"],
        ["8475.55", "101", "0", "1"],
        ["8475.54", "100", "0", "1"],
        ["8475.3", "1", "0", "1"],
        ["8447.32", "6", "0", "1"],
        ["8447.02", "246", "0", "1"],
        ["8446.83", "24", "0", "1"],
        ["8446", "95", "0", "3"]
      ],
      "ts": "1597026383085",
      "checksum": -855196043,
      "prevSeqId": 123456,
      "seqId": 123457
    }
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> instId	String	Instrument ID
action	String	Push data action, incremental data or full snapshot. `snapshot`: full `update`: incremental
data	Array	Subscribed data
> asks	Array	Order book on sell side
> bids	Array	Order book on buy side
> ts	String	Order book generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> checksum	Integer	Checksum, implementation details below
> prevSeqId	Integer	Sequence ID of the last sent message. Only applicable to `books`, `books-l2-tbt`, `books50-l2-tbt`
> seqId	Integer	Sequence ID of the current message, implementation details below

Sequence ID

seqId is the sequence ID of the market data published. The set of sequence ID received by users is the same if users are connecting to the same channel through multiple websocket connections. Each instId has an unique set of sequence ID. Users can use prevSeqId and seqId to build the message sequencing for incremental order book updates. Generally the value of seqId is larger than prevSeqId. The prevSeqId in the new message matches with seqId of the previous message. The smallest possible sequence ID value is 0, except in snapshot messages where the prevSeqId is always -1.

Exceptions:
1. If there are no updates to the depth for an extended period, OKX will send a message with 'asks': [], 'bids': [] to inform users that the connection is still active. seqId is the same as the last sent message and prevSeqId equals to seqId. 2. The sequence number may be reset due to maintenance, and in this case, users will receive an incremental message with seqId smaller than prevSeqId. However, subsequent messages will follow the regular sequencing rule.

Example

Snapshot message: prevSeqId = -1, seqId = 10
Incremental message 1 (normal update): prevSeqId = 10, seqId = 15
Incremental message 2 (no update): prevSeqId = 15, seqId = 15
Incremental message 3 (sequence reset): prevSeqId = 15, seqId = 3
Incremental message 4 (normal update): prevSeqId = 3, seqId = 5

Checksum

This mechanism can assist users in checking the accuracy of depth data.

Merging incremental data into full data

After subscribing to the incremental load push (such as books 400 levels) of Order Book Channel, users first receive the initial full load of market depth. After the incremental load is subsequently received, update the local full load.

If there is the same price, compare the size. If the size is 0, delete this depth data. If the size changes, replace the original data.
If there is no same price, sort by price (bid in descending order, ask in ascending order), and insert the depth information into the full load.

Calculate Checksum

Use the first 25 bids and asks in the full load to form a string (where a colon connects the price and size in an ask or a bid), and then calculate the CRC32 value (32-bit signed integer).

Calculate Checksum

1. More than 25 levels of bid and ask
A full load of market depth (only 2 levels of data are shown here, while 25 levels of data should actually be intercepted):

{
    "bids": [
        ["3366.1", "7", "0", "3"],
        ["3366", "6", "3", "4"]
    ],
    "asks": [
        ["3366.8", "9", "10", "3"],
        ["3368", "8", "3", "4"]
    ]
}

Check string:
"3366.1:7:3366.8:9:3366:6:3368:8"

2. Less than 25 levels of bid or ask
A full load of market depth:

{
    "bids": [
        ["3366.1", "7", "0", "3"]
    ],
    "asks": [
        ["3366.8", "9", "10", "3"],
        ["3368", "8", "3", "4"],
        ["3372", "8", "3", "4"]
    ]
}

Check string:
"3366.1:7:3366.8:9:3368:8:3372:8"

When the bid and ask depth data exceeds 25 levels, each of them will intercept 25 levels of data, and the string to be checked is queued in a way that the bid and ask depth data are alternately arranged.
Such as: bid[price:size]:ask[price:size]:bid[price:size]:ask[price:size]...
When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored.
Such as: bid[price:size]:ask[price:size]:asks[price:size]:asks[price:size]...

Push Data Example of bbo-tbt channel

{
  "arg": {
    "channel": "bbo-tbt",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        [
          "111.06","55154","0","2"
        ]
      ],
      "bids": [
        [
          "111.05","57745","0","2"
        ]
      ],
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

Push Data Example of books5 channel

{
  "arg": {
    "channel": "books5",
    "instId": "BCH-USDT-SWAP"
  },
  "data": [
    {
      "asks": [
        ["111.06","55154","0","2"],
        ["111.07","53276","0","2"],
        ["111.08","72435","0","2"],
        ["111.09","70312","0","2"],
        ["111.1","67272","0","2"]],
      "bids": [
        ["111.05","57745","0","2"],
        ["111.04","57109","0","2"],
        ["111.03","69563","0","2"],
        ["111.02","71248","0","2"],
        ["111.01","65090","0","2"]],
      "instId": "BCH-USDT-SWAP",
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

Public Data

The API endpoints of Public Data do not require authentication.

REST API

Get instruments

Retrieve a list of instruments with open contracts.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP + instrumentType

HTTP Request

GET /api/v5/public/instruments

Request Example

GET /api/v5/public/instruments?instType=SPOT

import okx.PublicData as PublicData

flag = "0"  # Production trading: 0, Demo trading: 1

publicDataAPI = PublicData.PublicAPI(flag=flag)

# Retrieve a list of instruments with open contracts
result = publicDataAPI.get_instruments(
    instType="SPOT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument type `SPOT`
instId	String	No	Instrument ID

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
      {
            "alias": "",
            "baseCcy": "BTC",
            "category": "1",
            "ctMult": "",
            "ctType": "",
            "ctVal": "",
            "ctValCcy": "",
            "expTime": "",
            "instFamily": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "10",
            "listTime": "1606468572000",
            "lotSz": "0.00000001",
            "maxIcebergSz": "9999999999.0000000000000000",
            "maxLmtAmt": "1000000",
            "maxLmtSz": "9999999999",
            "maxMktAmt": "1000000",
            "maxMktSz": "",
            "maxStopSz": "",
            "maxTriggerSz": "9999999999.0000000000000000",
            "maxTwapSz": "9999999999.0000000000000000",
            "minSz": "0.00001",
            "optType": "",
            "quoteCcy": "USDT",
            "settleCcy": "",
            "state": "live",
            "stk": "",
            "tickSz": "0.1",
            "uly": ""
        }
    ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID, e.g. `BTC-USDT`
uly	String	Underlying, e.g. `BTC-USD` Only applicable to `FUTURES`/`SWAP`/`OPTION`
instFamily	String	Instrument family, e.g. `BTC-USD` Only applicable to `FUTURES`/`SWAP`/`OPTION`
category	String	Currency category. Note: this parameter is already deprecated
baseCcy	String	Base currency, e.g. `BTC` in`BTC-USDT` Only applicable to `SPOT`/`MARGIN`
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT` Only applicable to `SPOT`/`MARGIN`
settleCcy	String	Settlement and margin currency, e.g. `BTC` Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctVal	String	Contract value Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctMult	String	Contract multiplier Only applicable to `FUTURES`/`SWAP`/`OPTION`
ctValCcy	String	Contract value currency Only applicable to `FUTURES`/`SWAP`/`OPTION`
optType	String	Option type, `C`: Call `P`: put Only applicable to `OPTION`
stk	String	Strike price Only applicable to `OPTION`
listTime	String	Listing time, Unix timestamp format in milliseconds, e.g. `1597026383085`
expTime	String	Expiry time Applicable to `SPOT`/`MARGIN`/`FUTURES`/`SWAP`/`OPTION`. For `FUTURES`/`OPTION`, it is natural delivery/exercise time. It is the instrument offline time when there is `SPOT/MARGIN/FUTURES/SWAP/` manual offline. Update once change.
lever	String	Max Leverage, Not applicable to `SPOT`, `OPTION`
tickSz	String	Tick size, e.g. `0.0001` For Option, it is minimum tickSz among tick band, please use "Get option tick bands" if you want get option tickBands.
lotSz	String	Lot size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
minSz	String	Minimum order size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
ctType	String	Contract type `linear`: linear contract `inverse`: inverse contract Only applicable to `FUTURES`/`SWAP`
alias	String	Alias `this_week` `next_week` `this_month` `next_month` `quarter` `next_quarter` Only applicable to `FUTURES` Not recommended for use, users are encouraged to rely on the expTime field to determine the delivery time of the contract
state	String	Instrument status `live` `suspend` `preopen`. e.g. There will be `preopen` before the Futures and Options new contracts state is live. `test`: Test pairs, can't be traded
maxLmtSz	String	The maximum order quantity of a single limit order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxMktSz	String	The maximum order quantity of a single market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.
maxLmtAmt	String	Max USD amount for a single limit order
maxMktAmt	String	Max USD amount for a single market order Only applicable to `SPOT`/`MARGIN`
maxTwapSz	String	The maximum order quantity of a single TWAP order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxIcebergSz	String	The maximum order quantity of a single iceBerg order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxTriggerSz	String	The maximum order quantity of a single trigger order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
maxStopSz	String	The maximum order quantity of a single stop market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.

Get system time

Retrieve API server time.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/public/time

Request Example

GET /api/v5/public/time

import okx.PublicData as PublicData

flag = "0"  # Production trading: 0, Demo trading: 1

publicDataAPI = PublicData.PublicAPI(flag=flag)

# Retrieve API server time
result = publicDataAPI.get_system_time()
print(result)

Response Example

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

Response Parameters

Parameter	Type	Description
ts	String	System time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get oracle

Get the crypto price of signing using Open Oracle smart contract.

Rate Limit: 1 request per 5 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/open-oracle

Request Example

GET /api/v5/market/open-oracle

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Get the crypto price of signing using Open Oracle smart contract
result = marketDataAPI.get_oracle()
print(result)

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "messages":[
                "0x000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000616d3b1400000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000e70528b800000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000"
            ],
            "prices":{
                "BTC":"62014"
            },
            "signatures":[
                "0xf18330e59eaf42373c2c40f1f9e24113ba21d4ed734dd3ed3bc1d12290fa74ba5623fca1113c5d245a1202dc065e333615b90f810f12132ce4a1ecacb8c6b24a000000000000000000000000000000000000000000000000000000000000001b"
            ],
            "timestamp":"1634548500"
        }
    ]
}

Response Parameters

Parameter	Type	Description
messages	String	ABI-encoded values [kind, timestamp, key, value], where kind equals 'prices', timestamp is the time when price was obtained, key is the asset ticker (e.g. btc) and value is the asset price.
prices	String	Readable asset prices
signatures	String	Ethereum-compatible ECDSA signatures for each message
timestamp	String	Time of latest datapoint, Unix timestamp, e.g. `1597026387`

Get exchange rate

This interface provides the average exchange rate data for 2 weeks

Rate Limit: 1 request per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/exchange-rate

Request Example

GET /api/v5/market/exchange-rate

import okx.MarketData as MarketData

flag = "0"  # Production trading:0 , demo trading:1

marketDataAPI =  MarketData.MarketAPI(flag=flag)

# Retrieve average exchange rate data for 2 weeks
result = marketDataAPI.get_exchange_rate()
print(result)

Response Example

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

Response Parameters

Parameter	Type	Description
usdCny	String	Exchange rate

Get economic calendar data

Get the macro-economic calendar data within 3 months. Historical data from 3 months ago is only available to users with trading fee tier VIP1 and above.

Rate Limit: 1 request per 5 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/public/economic-calendar

Request Example

GET /api/v5/public/economic-calendar

Request Parameters

Parameter	Type	Required	Description
region	string	No	Country, region or entity `afghanistan`, `albania`, `algeria`, `andorra`, `angola`, `antigua_and_barbuda`, `argentina`, `armenia`, `aruba`, `australia`, `austria`, `azerbaijan`, `bahamas`, `bahrain`, `bangladesh`, `barbados`, `belarus`, `belgium`, `belize`, `benin`, `bermuda`, `bhutan`, `bolivia`, `bosnia_and_herzegovina`, `botswana`, `brazil`, `brunei`, `bulgaria`, `burkina_faso`, `burundi`, `cambodia`, `cameroon`, `canada`, `cape_verde`, `cayman_islands`, `central_african_republic`, `chad`, `chile`, `china`, `colombia`, `comoros`, `congo`, `costa_rica`, `croatia`, `cuba`, `cyprus`, `czech_republic`, `denmark`, `djibouti`, `dominica`, `dominican_republic`, `east_timor`, `ecuador`, `egypt`, `el_salvador`, `equatorial_guinea`, `eritrea`, `estonia`, `ethiopia`, `euro_area`, `european_union`, `faroe_islands`, `fiji`, `finland`, `france`, `g20`, `g7`, `gabon`, `gambia`, `georgia`, `germany`, `ghana`, `greece`, `greenland`, `grenada`, `guatemala`, `guinea`, `guinea_bissau`, `guyana`, `hungary`, `haiti`, `honduras`, `hong_kong`, `hungary`, `imf`, `indonesia`, `iceland`, `india`, `indonesia`, `iran`, `iraq`, `ireland`, `isle_of_man`, `israel`, `italy`, `ivory_coast`, `jamaica`, `japan`, `jordan`, `kazakhstan`, `kenya`, `kiribati`, `kosovo`, `kuwait`, `kyrgyzstan`, `laos`, `latvia`, `lebanon`, `lesotho`, `liberia`, `libya`, `liechtenstein`, `lithuania`, `luxembourg`, `macau`, `macedonia`, `madagascar`, `malawi`, `malaysia`, `maldives`, `mali`, `malta`, `mauritania`, `mauritius`, `mexico`, `micronesia`, `moldova`, `monaco`, `mongolia`, `montenegro`, `morocco`, `mozambique`, `myanmar`, `namibia`, `nepal`, `netherlands`, `new_caledonia`, `new_zealand`, `nicaragua`, `niger`, `nigeria`, `north_korea`, `northern_mariana_islands`, `norway`, `opec`, `oman`, `pakistan`, `palau`, `palestine`, `panama`, `papua_new_guinea`, `paraguay`, `peru`, `philippines`, `poland`, `portugal`, `puerto_rico`, `qatar`, `russia`, `republic_of_the_congo`, `romania`, `russia`, `rwanda`, `slovakia`, `samoa`, `san_marino`, `sao_tome_and_principe`, `saudi_arabia`, `senegal`, `serbia`, `seychelles`, `sierra_leone`, `singapore`, `slovakia`, `slovenia`, `solomon_islands`, `somalia`, `south_africa`, `south_korea`, `south_sudan`, `spain`, `sri_lanka`, `st_kitts_and_nevis`, `st_lucia`, `sudan`, `suriname`, `swaziland`, `sweden`, `switzerland`, `syria`, `taiwan`, `tajikistan`, `tanzania`, `thailand`, `togo`, `tonga`, `trinidad_and_tobago`, `tunisia`, `turkey`, `turkmenistan`, `uganda`, `ukraine`, `united_arab_emirates`, `united_kingdom`, `united_states`, `uruguay`, `uzbekistan`, `vanuatu`, `venezuela`, `vietnam`, `world`, `yemen`, `zambia`, `zimbabwe`
importance	string	No	Level of importance `1`: low `2`: medium `3`: high
before	String	No	Pagination of data to return records newer than the requested ts based on the date parameter. Unix timestamp format in milliseconds.
after	String	No	Pagination of data to return records earlier than the requested ts based on the date parameter. Unix timestamp format in milliseconds. The default is the timestamp of the request moment.
limit	String	No	Number of results per request. The maximum is 100. The default is 100.

Response Example

{
    "code": "0",
    "data": [
        {
            "actual": "7.8%",
            "calendarId": "330631",
            "category": "Harmonised Inflation Rate YoY",
            "ccy": "",
            "date": "1700121600000",
            "dateSpan": "0",
            "event": "Harmonised Inflation Rate YoY",
            "forecast": "7.8%",
            "importance": "1",
            "prevInitial": "",
            "previous": "9%",
            "refDate": "1698710400000",
            "region": "Slovakia",
            "uTime": "1700121605007",
            "unit": "%"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
calendarId	string	Calendar ID
date	string	Estimated release time of the value of actual field, millisecond format of Unix timestamp, e.g. `1597026383085`
region	string	Country, region or entity
category	string	Category name
event	string	Event name
refDate	string	Date for which the datapoint refers to
actual	string	The actual value of this event
previous	string	Latest actual value of the previous period The value will be revised if revision is applicable
forecast	string	Average forecast among a representative group of economists
dateSpan	string	`0`: The time of the event is known `1`: we only know the date of the event, the exact time of the event is unknown.
importance	string	Level of importance `1`: low `2`: medium `3`: high
uTime	string	Update time of this record, millisecond format of Unix timestamp, e.g. `1597026383085`
prevInitial	string	The initial value of the previous period Only applicable when revision happens
ccy	string	Currency of the data
unit	string	Unit of the data

WebSocket

Instruments channel

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "instruments",
      "instType": "SPOT"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `instruments`
> instType	String	Yes	Instrument type `SPOT`

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "instruments",
    "instType": "SPOT"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"instruments\", \"instType\" : \"FUTURES\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instType	String	Yes	Instrument type `SPOT`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
  "arg": {
    "channel": "instruments",
    "instType": "SPOT"
  },
  "data": [
    {
        "alias": "",
        "baseCcy": "BTC",
        "category": "1",
        "ctMult": "",
        "ctType": "",
        "ctVal": "",
        "ctValCcy": "",
        "expTime": "",
        "instFamily": "",
        "instId": "BTC-USDT",
        "instType": "SPOT",
        "lever": "10",
        "listTime": "1606468572000",
        "lotSz": "0.00000001",
        "maxIcebergSz": "9999999999.0000000000000000",
        "maxLmtAmt": "1000000",
        "maxLmtSz": "9999999999",
        "maxMktAmt": "1000000",
        "maxMktSz": "",
        "maxStopSz": "",
        "maxTriggerSz": "9999999999.0000000000000000",
        "maxTwapSz": "9999999999.0000000000000000",
        "minSz": "0.00001",
        "optType": "",
        "quoteCcy": "USDT",
        "settleCcy": "",
        "state": "live",
        "stk": "",
        "tickSz": "0.1",
        "uly": ""
    }
  ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Subscribed channel
> channel	String	Channel name
> instType	String	Instrument type
data	Array	Subscribed data
> instType	String	Instrument type
> instId	String	Instrument ID, e.g. `BTC-UST`
> uly	String	Underlying, e.g. `BTC-USD` Only applicable to `FUTURES`/`SWAP`/`OPTION`
> instFamily	String	Instrument family, e.g. `BTC-USD` Only applicable to `FUTURES`/`SWAP`/`OPTION`
> category	String	Currency category. Note: this parameter is already deprecated
> baseCcy	String	Base currency, e.g. `BTC` in `BTC-USDT` Only applicable to `SPOT`/`MARGIN`
> quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT` Only applicable to `SPOT`/`MARGIN`
> settleCcy	String	Settlement and margin currency, e.g. `BTC` Only applicable to `FUTURES`/`SWAP`/`OPTION`
> ctVal	String	Contract value
> ctMult	String	Contract multiplier
> ctValCcy	String	Contract value currency
> optType	String	Option type `C`: Call `P`: Put Only applicable to `OPTION`
> stk	String	Strike price Only applicable to `OPTION`
> listTime	String	Listing time Only applicable to `FUTURES`/`SWAP`/`OPTION`
> expTime	String	Expiry time Applicable to `SPOT`/`MARGIN`/`FUTURES`/`SWAP`/`OPTION`. For `FUTURES`/`OPTION`, it is the delivery/exercise time. It can also be the delisting time of the trading instrument. Update once change.
> lever	String	Max Leverage Not applicable to `SPOT`/`OPTION`, used to distinguish between `MARGIN` and `SPOT`.
> tickSz	String	Tick size, e.g. `0.0001` For Option, it is minimum tickSz among tick band.
> lotSz	String	Lot size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`
> minSz	String	Minimum order size If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`
> ctType	String	Contract type `linear`: linear contract `inverse`: inverse contract Only applicable to `FUTURES`/`SWAP`
> alias	String	Alias `this_week` `next_week` `this_month` `next_month` `quarter` `next_quarter` Only applicable to `FUTURES` Not recommended for use, users are encouraged to rely on the expTime field to determine the delivery time of the contract
> state	String	Instrument status `live` `suspend` `expired` `preopen`. e.g. There will be preopen before the Futures and Options new contracts state is live. `test`: Test pairs, can't be traded
> maxLmtSz	String	The maximum order quantity of a single limit order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
> maxMktSz	String	The maximum order quantity of a single market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.
> maxTwapSz	String	The maximum order quantity of a single TWAP order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
> maxIcebergSz	String	The maximum order quantity of a single iceBerg order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
> maxTriggerSz	String	The maximum order quantity of a single trigger order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `base currency`.
> maxStopSz	String	The maximum order quantity of a single stop market order. If it is a derivatives contract, the value is the number of contracts. If it is `SPOT`/`MARGIN`, the value is the quantity in `USDT`.

Economic calendar channel

Retrieve the most up-to-date economic calendar data. This endpoint is only applicable to VIP 1 and above users in the trading fee tier.

URL Path

/ws/v5/business (required login)

Request Example

{
    "op": "subscribe",
    "args": [
      {
          "channel": "economic-calendar"
      }
    ]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `economic-calendar`

Successful Response Example

{
    "event": "subscribe",
    "arg": {
        "channel": "economic-calendar"
    }
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price\", \"instId\" : \"LTC-USD-190628\"}]}"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Event `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "economic-calendar"
    },
    "data": [
        {
            "calendarId": "319275",
            "date": "1597026383085",
            "region": "United States",
            "category": "Manufacturing PMI",
            "event": "S&P Global Manufacturing PMI Final",
            "refDate": "1597026383085",
            "actual": "49.2",
            "previous": "47.3",
            "forecast": "49.3",
            "importance": "2",
            "prevInitial": "",
            "ccy": "",
            "unit": "",
            "ts": "1698648096590"
        }
    ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
data	Array	Subscribed data
> event	string	Event name
> region	string	Country, region or entity
> category	string	Category name
> actual	string	The actual value of this event
> previous	string	Latest actual value of the previous period The value will be revised if revision is applicable
> forecast	string	Average forecast among a representative group of economists
> prevInitial	string	The initial value of the previous period Only applicable when revision happens
> date	string	Estimated release time of the value of actual field, millisecond format of Unix timestamp, e.g. `1597026383085`
> refDate	string	Date for which the datapoint refers to
> calendarId	string	Calendar ID
> unit	string	Unit of the data
> ccy	string	Currency of the data
> importance	string	Level of importance `1`: low `2`: medium `3`: high
> ts	string	The time of the latest update

Funding Account

The API endpoints of Funding Account require authentication.

REST API

Get currencies

Retrieve a list of all currencies available which are related to the current account's KYC entity.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/currencies

Request Example

GET /api/v5/asset/currencies

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get currencies
result = fundingAPI.get_currencies()
print(result)

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Single currency or multiple currencies separated with comma, e.g. `BTC` or `BTC,ETH`.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "canDep": true,
        "canInternal": true,
        "canWd": true,
        "ccy": "BTC",
        "chain": "BTC-Bitcoin",
        "depQuotaFixed": "",
        "depQuoteDailyLayer2": "",
        "logoLink": "https://static.coinall.ltd/cdn/oksupport/asset/currency/icon/btc.png",
        "mainNet": true,
        "maxFee": "0.0004",
        "maxFeeForCtAddr": "0.0004",
        "maxWd": "500",
        "minDep": "0.00005",
        "minDepArrivalConfirm": "1",
        "minFee": "0.0002",
        "minFeeForCtAddr": "0.0002",
        "minWd": "0.001",
        "minWdUnlockConfirm": "3",
        "name": "Bitcoin",
        "needTag": false,
        "usedDepQuotaFixed": "",
        "usedWdQuota": "0",
        "wdQuota": "200",
        "wdTickSz": "8"
    }
  ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency, e.g. `BTC`
name	String	Name of currency. There is no related name when it is not shown.
logoLink	String	The logo link of currency
chain	String	Chain name, e.g. `USDT-ERC20`, `USDT-TRC20`
canDep	Boolean	The availability to deposit from chain `false`: not available `true`: available
canWd	Boolean	The availability to withdraw to chain `false`: not available `true`: available
canInternal	Boolean	The availability to internal transfer `false`: not available `true`: available
minDep	String	The minimum deposit amount of currency in a single transaction
minWd	String	The minimum `on-chain withdrawal` amount of currency in a single transaction
maxWd	String	The maximum amount of currency `on-chain withdrawal` in a single transaction
wdTickSz	String	The withdrawal precision, indicating the number of digits after the decimal point. The withdrawal fee precision kept the same as withdrawal precision. The accuracy of internal transfer withdrawal is 8 decimal places.
wdQuota	String	The withdrawal limit in the past 24 hours (including `on-chain withdrawal` and `internal transfer`), unit in `USD`
usedWdQuota	String	The amount of currency withdrawal used in the past 24 hours, unit in `USD`
minFee	String	The minimum withdrawal fee for normal address Apply to `on-chain withdrawal`
maxFee	String	The maximum withdrawal fee for normal address Apply to `on-chain withdrawal`
minFeeForCtAddr	String	The minimum withdrawal fee for contract address Apply to `on-chain withdrawal`
maxFeeForCtAddr	String	The maximum withdrawal fee for contract address Apply to `on-chain withdrawal`
mainNet	Boolean	If current chain is main net, then it will return `true`, otherwise it will return `false`
needTag	Boolean	Whether tag/memo information is required for withdrawal, e.g. `EOS` will return `true`
minDepArrivalConfirm	String	The minimum number of blockchain confirmations to acknowledge fund deposit. The account is credited after that, but the deposit can not be withdrawn
minWdUnlockConfirm	String	The minimum number of blockchain confirmations required for withdrawal of a deposit
depQuotaFixed	String	The fixed deposit limit, unit in `USD` Return empty string if there is no deposit limit
usedDepQuotaFixed	String	The used amount of fixed deposit quota, unit in `USD` Return empty string if there is no deposit limit
depQuoteDailyLayer2	String	The layer2 network daily deposit limit

Get balance

Retrieve the funding account balances of all the assets and the amount that is available or on hold.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/balances

Request Example

GET /api/v5/asset/balances

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get balane
result = fundingAPI.get_balances()
print(result)

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "availBal": "37.11827078",
            "bal": "37.11827078",
            "ccy": "ETH",
            "frozenBal": "0"
        }
    ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
bal	String	Balance
frozenBal	String	Frozen balance
availBal	String	Available balance

Get non-tradable assets

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/non-tradable-assets

Request Example

GET /api/v5/asset/non-tradable-assets

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

result = fundingAPI.get_non_tradable_assets()
print(result)

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Response Example

{
    "code": "0",
    "data": [
        {
            "bal": "989.84719571",
            "canWd": true,
            "ccy": "CELT",
            "chain": "CELT-OKTC",
            "ctAddr": "f403fb",
            "fee": "2",
            "logoLink": "https://static.coinall.ltd/cdn/assets/imgs/221/460DA8A592400393.png",
            "minWd": "0.1",
            "name": "",
            "needTag": false,
            "wdAll": false,
            "wdTickSz": "8"
        },
        {
            "bal": "0.001",
            "canWd": true,
            "ccy": "MEME",
            "chain": "MEME-ERC20",
            "ctAddr": "09b760",
            "fee": "5",
            "logoLink": "https://static.coinall.ltd/cdn/assets/imgs/207/2E664E470103C613.png",
            "minWd": "0.001",
            "name": "MEME Inu",
            "needTag": false,
            "wdAll": false,
            "wdTickSz": "8"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency, e.g. `CELT`
name	String	Chinese name of currency. There is no related name when it is not shown.
logoLink	String	Logo link of currency
bal	String	Withdrawable balance
canWd	Boolean	Availability to withdraw to chain. `false`: not available `true`: available
chain	String	Chain for withdrawal
minWd	String	Minimum withdrawal amount of currency in a single transaction
wdAll	Boolean	Whether all assets in this currency must be withdrawn at one time
fee	String	Fixed withdrawal fee, unit in `USDT`. Withdrawal fee precision is 8 digits after the decimal point.
ctAddr	String	Last 6 digits of contract address
wdTickSz	String	Withdrawal precision, indicating the number of digits after the decimal point
needTag	Boolean	Whether tag/memo information is required for withdrawal

Get account asset valuation

View account asset valuation

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/asset-valuation

Request Example

GET /api/v5/asset/asset-valuation

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get account asset valuation
result = fundingAPI.get_asset_valuation()
print(result)

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Asset valuation calculation unit BTC, USDT USD, CNY, JP, KRW, RUB, EUR VND, IDR, INR, PHP, THB, TRY AUD, SGD, ARS, SAR, AED, IQD The default is the valuation in BTC.

Response Example

{
    "code": "0",
    "data": [
        {
            "details": {
                "classic": "124.6",
                "earn": "1122.73",
                "funding": "0.09",
                "trading": "2544.28"
            },
            "totalBal": "3790.09",
            "ts": "1637566660769"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
totalBal	String	Valuation of total account assets
ts	String	Unix timestamp format in milliseconds, e.g.`1597026383085`
details	Object	Asset valuation details for each account
> funding	String	Funding account
> trading	String	Trading account
> classic	String	[Deprecated] Classic account
> earn	String	Earn account

Funds transfer

Only API keys with Trade privilege can call this endpoint.

This endpoint supports the transfer of funds between your funding account and trading account, and from the master account to sub-accounts.

Sub-account can transfer out to master account by default. Need to call Set permission of transfer out to grant privilege first if you want sub-account transferring to another sub-account (sub-accounts need to belong to same master account.)

Rate Limit: 2 requests per second

Rate limit rule: UserID + Currency

HTTP Request

POST /api/v5/asset/transfer

Request Example

# Transfer 1.5 USDT from funding account to Trading account when current account is master-account
POST /api/v5/asset/transfer
body
{
    "ccy":"USDT",
    "amt":"1.5",
    "from":"6",
    "to":"18"
}

# Transfer 1.5 USDT from funding account to subAccount when current account is master-account
POST /api/v5/asset/transfer
body
{
    "ccy":"USDT",
    "type":"1",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "subAcct":"mini"
}

# Transfer 1.5 USDT from funding account to subAccount when current account is sub-account
POST /api/v5/asset/transfer
body 
{
    "ccy":"USDT",
    "type":"4",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "subAcct":"mini"
}

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Funds transfer
result = fundingAPI.funds_transfer(
    ccy="USDT",
    amt="1.5",
    from_="6",
    to="18"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
type	String	No	Transfer type `0`: transfer within account `1`: master account to sub-account (Only applicable to API Key from master account) `2`: sub-account to master account (Only applicable to API Key from master account) `3`: sub-account to master account (Only applicable to APIKey from sub-account) `4`: sub-account to sub-account (Only applicable to APIKey from sub-account, and target account needs to be another sub-account which belongs to same master account. Sub-account directly transfer out permission is disabled by default, set permission please refer to Set permission of transfer out) The default is `0`. If you want to make transfer between sub-accounts by master account API key, refer to Master accounts manage the transfers between sub-accounts
ccy	String	Yes	Transfer currency, e.g. `USDT`
amt	String	Yes	Amount to be transferred
from	String	Yes	The remitting account `6`: Funding account `18`: Trading account
to	String	Yes	The beneficiary account `6`: Funding account `18`: Trading account
subAcct	String	Conditional	Name of the sub-account When `type` is `1`/`2`/`4`, this parameter is required.
loanTrans	Boolean	No	Whether or not borrowed coins can be transferred out under `Multi-currency margin` and `Portfolio margin` `true`: borrowed coins can be transferred out `false`: borrowed coins cannot be transferred out the default is `false`
omitPosRisk	String	No	Ignore position risk Default is `false` Applicable to `Portfolio margin`
clientId	String	No	Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "transId": "754147",
      "ccy": "USDT",
      "clientId": "",
      "from": "6",
      "amt": "0.1",
      "to": "18"
    }
  ]
}

Response Parameters

Response Example

Parameter	Type	Description
transId	String	Transfer ID
clientId	String	Client-supplied ID
ccy	String	Currency
from	String	The remitting account
amt	String	Transfer amount
to	String	The beneficiary account

Get funds transfer state

Retrieve the transfer state data of the last 2 weeks.

Rate Limit: 10 request per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/transfer-state

Request Example

GET /api/v5/asset/transfer-state?transId=1&type=1

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get funds transfer state
result = fundingAPI.transfer_state(
    transId="248424899",
    type="0"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
transId	String	Conditional	Transfer ID Either transId or clientId is required. If both are passed, transId will be used.
clientId	String	Conditional	Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
type	String	No	Transfer type `0`: transfer within account `1`: master account to sub-account (Only applicable to API Key from master account) `2`: sub-account to master account (Only applicable to API Key from master account) `3`: sub-account to master account (Only applicable to APIKey from sub-account) `4`: sub-account to sub-account (Only applicable to APIKey from sub-account, and target account needs to be another sub-account which belongs to same master account) The default is `0`

Response Example

{
    "code": "0",
    "data": [
        {
            "amt": "1.5",
            "ccy": "USDT",
            "clientId": "",
            "from": "18",
            "instId": "", //deprecated
            "state": "success",
            "subAcct": "test",
            "to": "6",
            "toInstId": "", //deprecated
            "transId": "1",
            "type": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
transId	String	Transfer ID
clientId	String	Client-supplied ID
ccy	String	Currency, e.g. `USDT`
amt	String	Amount to be transferred
type	String	Transfer type `0`: transfer within account `1`: master account to sub-account (Only applicable to API Key from master account) `2`: sub-account to master account (Only applicable to APIKey from master account) `3`: sub-account to master account (Only applicable to APIKey from sub-account) `4`: sub-account to sub-account (Only applicable to APIKey from sub-account, and target account needs to be another sub-account which belongs to same master account)
from	String	The remitting account `6`: Funding account `18`: Trading account
to	String	The beneficiary account `6`: Funding account `18`: Trading account
subAcct	String	Name of the sub-account
instId	String	deprecated
toInstId	String	deprecated
state	String	Transfer state `success` `pending` `failed`

Asset bills details

Query the billing record in the past month.

Rate Limit: 6 Requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/bills

Request Example

GET /api/v5/asset/bills

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get asset bills details
result = fundingAPI.get_bills()
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	No	Currency
type	String	No	Bill type `1`: Deposit `2`: Withdrawal `13`: Canceled withdrawal `20`: Transfer to sub account (for master account) `21`: Transfer from sub account (for master account) `22`: Transfer out from sub to master account (for sub-account) `23`: Transfer in from master to sub account (for sub-account) `28`: Manually claimed Airdrop `47`: System reversal `48`: Event Reward `49`: Event Giveaway `61`: [Convert] Exchange between crypto `68`: Fee rebate (by rebate card) `72`: Token received `73`: Token given away `74`: Token refunded `75`: Subscription to savings `76`: Redemption to savings `77`: Jumpstart distribute `78`: Jumpstart lock up `80`: DEFI/Staking purchase `82`: DEFI/Staking redemption `83`: Staking yield `84`: Violation fee `116`: [Fiat] Place an order `117`: [Fiat] Fulfill an order `118`: [Fiat] Cancel an order `124`: Jumpstart unlocking `130`: Transferred from Trading account `131`: Transferred to Trading account `132`: [P2P] Frozen by customer service `133`: [P2P] Unfrozen by customer service `134`: [P2P] Transferred by customer service `135`: Cross chain exchange `136`: ETH 2.0 staking system account increase ETH (for on-chain operation) `137`: ETH 2.0 Subscription `138`: ETH 2.0 Swapping `139`: ETH 2.0 Earnings `146`: Customer feedback `150`: Affiliate commission `151`: Referral reward `152`: Broker reward `160`: Dual Investment subscribe `161`: Dual Investment collection `162`: Dual Investment profit `163`: Dual Investment refund `172`: [Affiliate] Sub-affiliate commission `173`: [Affiliate] Fee rebate (by trading fee) `174`: Jumpstart Pay `175`: Locked collateral `176`: Loan `177`: Added collateral `178`: Returned collateral `179`: Repayment `180`: Unlocked collateral `181`: Airdrop payment `185`: [Broker] Convert reward `187`: [Broker] Convert transfer `189`: Mystery box bonus `195`: Untradable asset withdrawal `196`: Untradable asset withdrawal revoked `197`: Untradable asset deposit `198`: Untradable asset collection reduce `199`: Untradable asset collection increase `200`: Buy `202`: Price Lock Subscribe `203`: Price Lock Collection `204`: Price Lock Profit `205`: Price Lock Refund `207`: Dual Investment Lite Subscribe `208`: Dual Investment Lite Collection `209`: Dual Investment Lite Profit `210`: Dual Investment Lite Refund `212`: [Flexible loan] Multi-collateral loan collateral locked `214`: [Flexible loan] Collateral returned to users `216`: [Flexible loan] Loan transfer into user's funding account `218`: [Flexible loan] Multi-collateral loan repaid `220`: Delisted crypto `221`: Blockchain's withdrawal fee `222`: Withdrawal fee refund `223`: SWAP lead trading profit share `225`: Shark Fin subscribe `226`: Shark Fin collection `227`: Shark Fin profit `228`: Shark Fin refund `229`: Airdrop `233`: Broker rebate compensation `240`: Snowball subscribe `241`: Snowball refund `242`: Snowball profit `243`: Snowball trading failed `249`: Seagull subscribe `250`: Seagull collection `251`: Seagull profit `252`: Seagull refund `263`: Strategy bots profit share `265`: Signal revenue `266`: SPOT lead trading profit share `270`: DCD broker transfer `271`: DCD broker rebate `272`: [Convert] Buy Crypto/Fiat `273`: [Convert] Sell Crypto/Fiat `284`: [Custody] Transfer out trading sub-account `285`: [Custody] Transfer in trading sub-account `286`: [Custody] Transfer out custody funding account `287`: [Custody] Transfer in custody funding account `288`: [Custody] Fund delegation `289`: [Custody] Fund undelegation `299`: Affiliate recommendation commission `300`: Fee discount rebate `303`: Snowball market maker transfer `304`: Simple Earn Fixed order submission `305`: Simple Earn Fixed order redemption `306`: Simple Earn Fixed principal distribution `307`: Simple Earn Fixed interest distribution (early termination compensation) `308`: Simple Earn Fixed interest distribution `309`: Simple Earn Fixed interest distribution (extension compensation) `311`: Crypto dust auto-transfer in
clientId	String	No	Client-supplied ID for transfer or withdrawal A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
after	String	No	Pagination of data to return records earlier than the requested `ts`, Unix timestamp format in milliseconds, e.g. `1597026383085`
before	String	No	Pagination of data to return records newer than the requested `ts`, Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "billId": "12344",
        "ccy": "BTC",
        "clientId": "",
        "balChg": "2",
        "bal": "12",
        "type": "1",
        "ts": "1597026383085"
    }]
}

Response Parameters

Parameter	Type	Description
billId	String	Bill ID
ccy	String	Account balance currency
clientId	String	Client-supplied ID for transfer or withdrawal
balChg	String	Change in balance at the account level
bal	String	Balance at the account level
type	String	Bill type
ts	String	Creation time, Unix timestamp format in milliseconds, e.g.`1597026383085`

Get deposit address

Retrieve the deposit addresses of currencies, including previously-used addresses.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-address

Request Example

GET /api/v5/asset/deposit-address?ccy=BTC

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get deposit address
result = fundingAPI.get_deposit_address(
    ccy="USDT"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	Yes	Currency, e.g. `BTC`

Response Example

{
    "code": "0",
    "data": [
        {
            "chain": "BTC-Bitcoin",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "39XNxK1Ryqgg3Bsyn6HzoqV4Xji25pNkv6",
            "verifiedName":"John Corner",
            "selected": true
        },
        {
            "chain": "BTC-OKC",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "verifiedName":"John Corner",
            "selected": true
        },
        {
            "chain": "BTC-ERC20",
            "ctAddr": "5807cf",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "verifiedName":"John Corner",
            "selected": true
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
addr	String	Deposit address
tag	String	Deposit tag (This will not be returned if the currency does not require a tag for deposit)
memo	String	Deposit memo (This will not be returned if the currency does not require a memo for deposit)
pmtId	String	Deposit payment ID (This will not be returned if the currency does not require a payment_id for deposit)
addrEx	Object	Deposit address attachment (This will not be returned if the currency does not require this) e.g. `TONCOIN` attached tag name is `comment`, the return will be `{'comment':'123456'}`
ccy	String	Currency, e.g. `BTC`
chain	String	Chain name, e.g. `USDT-ERC20`, `USDT-TRC20`
to	String	The beneficiary account `6`: Funding account `18`: Trading account
verifiedName	String	Verified name (for recipient)
selected	Boolean	Return `true` if the current deposit address is selected by the website page
ctAddr	String	Last 6 digits of contract address

Get deposit history

Retrieve the deposit records according to the currency, deposit status, and time range in reverse chronological order. The 100 most recent records are returned by default.
Websocket API is also available, refer to Deposit info channel.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-history

Request Example


GET /api/v5/asset/deposit-history

# Query deposit history from 2022-06-01 to 2022-07-01
GET /api/v5/asset/deposit-history?ccy=BTC&after=1654041600000&before=1656633600000

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Get deposit history
result = fundingAPI.get_deposit_history()
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	No	Currency, e.g. `BTC`
depId	String	No	Deposit ID
fromWdId	String	No	Internal transfer initiator's withdrawal ID If the deposit comes from internal transfer, this field displays the withdrawal ID of the internal transfer initiator
txId	String	No	Hash record of the deposit
type	String	No	Deposit Type `3`: internal transfer `4`: deposit from chain
state	String	No	Status of deposit `0`: waiting for confirmation `1`: deposit credited `2`: deposit successful `8`: pending due to temporary deposit suspension on this crypto currency `11`: match the address blacklist `12`: account or deposit is frozen `13`: sub-account deposit interception `14`: KYC limit
after	String	No	Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. `1654041600000`
before	String	No	Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. `1656633600000`
limit	string	No	Number of results per request. The maximum is `100`; The default is `100`

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "actualDepBlkConfirm": "2",
        "amt": "1",
        "areaCodeFrom": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "depId": "88****33",
        "from": "",
        "fromWdId": "",
        "state": "2",
        "to": "TN4hGjVXMzy*********9b4N1aGizqs",
        "ts": "1674038705000",
        "txId": "fee235b3e812********857d36bb0426917f0df1802"
    }
  ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
chain	String	Chain name
amt	String	Deposit amount
from	String	Deposit account If the deposit comes from an internal transfer, this field displays the account information of the internal transfer initiator, which can be a mobile phone number, email address, account name, and will return "" in other cases
areaCodeFrom	String	If `from` is a phone number, this parameter return area code of the phone number
to	String	Deposit address If the deposit comes from the on-chain, this field displays the on-chain address, and will return "" in other cases
txId	String	Hash record of the deposit
ts	String	The timestamp that the deposit record is created, Unix timestamp format in milliseconds, e.g. `1655251200000`
state	String	Status of deposit `0`: Waiting for confirmation `1`: Deposit credited `2`: Deposit successful `8`: Pending due to temporary deposit suspension on this crypto currency `11`: Match the address blacklist `12`: Account or deposit is frozen `13`: Sub-account deposit interception `14`: KYC limit
depId	String	Deposit ID
fromWdId	String	Internal transfer initiator's withdrawal ID If the deposit comes from internal transfer, this field displays the withdrawal ID of the internal transfer initiator, and will return "" in other cases
actualDepBlkConfirm	String	The actual amount of blockchain confirmed in a single deposit

Withdrawal

Withdrawal of tokens. Common sub-account does not support withdrawal.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/withdrawal

Request Example

# on-chain withdrawal
POST /api/v5/asset/withdrawal
body
{
    "amt":"1",
    "fee":"0.0005",
    "dest":"4",
    "ccy":"BTC",
    "chain":"BTC-Bitcoin",
    "toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"
}

# internal withdrawal 
POST /api/v5/asset/withdrawal
body
{
    "amt":"10",
    "fee":"0",
    "dest":"3",
    "ccy":"USDT",
    "areaCode":"86",
    "toAddr":"15651000000"
}

# Specific entity users need to provide receiver's info
POST /api/v5/asset/withdrawal
body
{
    "amt":"1",
    "fee":"0.0005",
    "dest":"4",
    "ccy":"BTC",
    "chain":"BTC-Bitcoin",
    "toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw",
    "rcvrInfo":{
        "walletType":"exchange",
        "exchId":"did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1",
        "rcvrFirstName":"Bruce",
        "rcvrLastName":"Wayne"
    }
}

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Withdrawal
result = fundingAPI.withdrawal(
    ccy="USDT",
    toAddr="TXtvfb7cdrn6VX9H49mgio8bUxZ3DGfvYF",
    amt="100",
    fee="0.0005",
    dest="4",
    chain="USDT-TRC20"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	Yes	Currency, e.g. `USDT`
amt	String	Yes	Withdrawal amount Withdrawal fee is not included in withdrawal amount.
dest	String	Yes	Withdrawal method `3`: internal transfer `4`: on-chain withdrawal
toAddr	String	Yes	`toAddr` should be a trusted address/account. If your `dest` is `4`, some crypto currency addresses are formatted as `'address:tag'`, e.g. `'ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456'` If your `dest` is `3`,`toAddr` should be a recipient address which can be email, phone or login account name (account name is only for sub-account).
fee	String	Yes	Transaction fee You can get fee amount by the endpoint of Get currencies. For `internal transfer`, transaction fee is always `0`.
chain	String	Conditional	Chain name There are multiple chains under some currencies, such as `USDT` has `USDT-ERC20`, `USDT-TRC20` If the parameter is not filled in, the default will be the main chain. When you withdrawal the non-tradable asset, if the parameter is not filled in, the default will be the unique withdrawal chain. Apply to `on-chain withdrawal`. You can get supported chain name by the endpoint of Get currencies.
areaCode	String	Conditional	Area code for the phone number, e.g. `86` If `toAddr` is a phone number, this parameter is required. Apply to `internal transfer`
rcvrInfo	Object	Conditional	Recipient information For the specific entity users to do on-chain withdrawal/lightning withdrawal, this information is required.
> walletType	String	Yes	Wallet Type `exchange`: Withdraw to exchange wallet `private`: Withdraw to private wallet If withdrawal to the exchange wallet, relevant information about the recipient must be provided. For the exchange wallet belongs to business recipient, `rcvrFirstName` may input the company name, `rcvrLastName` may input "N/A", location info may input the registered address of the company. Withdrawal to a private wallet does not require providing recipient information.
> exchId	String	Conditional	Exchange ID You can query supported exchanges through the endpoint of Get exchange list (public) If the exchange is not in the exchange list, fill in '0' in this field. Apply to walletType = `exchange`
> rcvrFirstName	String	Conditional	Receiver's first name, e.g. `Bruce` Apply to walletType = `exchange`
> rcvrLastName	String	Conditional	Receiver's last name, e.g. `Wayne` Apply to walletType = `exchange`
> rcvrCountry	String	Conditional	The recipient's country, e.g. `United States` You must enter an English country name or a two letter country code (ISO 3166-1). Please refer to the `Country Name` and `Country Code` in the country information table below. Apply to walletType = `exchange`
> rcvrCountrySubDivision	String	Conditional	State/Province of the recipient, e.g. `California` Apply to walletType = `exchange`
> rcvrTownName	String	Conditional	The town/city where the recipient is located, e.g. `San Jose` Apply to walletType = `exchange`
> rcvrStreetName	String	Conditional	Recipient's street address, e.g. `Clementi Avenue 1` Apply to walletType = `exchange`
clientId	String	No	Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "amt": "0.1",
        "wdId": "67485",
        "ccy": "BTC",
        "clientId": "",
        "chain": "BTC-Bitcoin"
    }]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
chain	String	Chain name, e.g. `USDT-ERC20`, `USDT-TRC20`
amt	String	Withdrawal amount
wdId	String	Withdrawal ID
clientId	String	Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Country information

Country name	Country code
Afghanistan	AF
Albania	AL
Algeria	DZ
Andorra	AD
Angola	AO
Anguilla	AI
Antigua and Barbuda	AG
Argentina	AR
Armenia	AM
Australia	AU
Austria	AT
Azerbaijan	AZ
Bahamas	BS
Bahrain	BH
Bangladesh	BD
Barbados	BB
Belarus	BY
Belgium	BE
Belize	BZ
Benin	BJ
Bermuda	BM
Bhutan	BT
Bolivia	BO
Bosnia and Herzegovina	BA
Botswana	BW
Brazil	BR
British Virgin Islands	VG
Brunei	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cambodia	KH
Cameroon	CM
Canada	CA
Cape Verde	CV
Cayman Islands	KY
Central African Republic	CF
Chad	TD
Chile	CL
Colombia	CO
Comoros	KM
Congo (Republic)	CG
Congo (Democratic Republic)	CD
Costa Rica	CR
Cote d´Ivoire (Ivory Coast)	CI
Croatia	HR
Cuba	CU
Cyprus	CY
Czech Republic	CZ
Denmark	DK
Djibouti	DJ
Dominica	DM
Dominican Republic	DO
Ecuador	EC
Egypt	EG
El Salvador	SV
Equatorial Guinea	GQ
Eritrea	ER
Estonia	EE
Ethiopia	ET
Fiji	FJ
Finland	FI
France	FR
Gabon	GA
Gambia	GM
Georgia	GE
Germany	DE
Ghana	GH
Greece	GR
Grenada	GD
Guatemala	GT
Guinea	GN
Guinea-Bissau	GW
Guyana	GY
Haiti	HT
Honduras	HN
Hong Kong	HK
Hungary	HU
Iceland	IS
India	IN
Indonesia	ID
Iran	IR
Iraq	IQ
Ireland	IE
Israel	IL
Italy	IT
Jamaica	JM
Japan	JP
Jordan	JO
Kazakhstan	KZ
Kenya	KE
Kiribati	KI
North Korea	KP
South Korea	KR
Kuwait	KW
Kyrgyzstan	KG
Laos	LA
Latvia	LV
Lebanon	LB
Lesotho	LS
Liberia	LR
Libya	LY
Liechtenstein	LI
Lithuania	LT
Luxembourg	LU
Macau	MO
Macedonia	MK
Madagascar	MG
Malawi	MW
Malaysia	MY
Maldives	MV
Mali	ML
Malta	MT
Marshall Islands	MH
Mauritania	MR
Mauritius	MU
Mexico	MX
Micronesia	FM
Moldova	MD
Monaco	MC
Mongolia	MN
Montenegro	ME
Morocco	MA
Mozambique	MZ
Myanmar (Burma)	MM
Namibia	NA
Nauru	NR
Nepal	NP
Netherlands	NL
New Zealand	NZ
Nicaragua	NI
Niger	NE
Nigeria	NG
Norway	NO
Oman	OM
Pakistan	PK
Palau	PW
Panama	PA
Papua New Guinea	PG
Paraguay	PY
Peru	PE
Philippines	PH
Poland	PL
Portugal	PT
Qatar	QA
Romania	RO
Russia	RU
Rwanda	RW
Saint Kitts and Nevis	KN
Saint Lucia	LC
Saint Vincent and the Grenadines	VC
Samoa	WS
San Marino	SM
Sao Tome and Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
Somalia	SO
South Africa	ZA
Spain	ES
Sri Lanka	LK
Sudan	SD
Suriname	SR
Swaziland	SZ
Sweden	SE
Switzerland	CH
Syria	SY
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
Timor-Leste (East Timor)	TL
Togo	TG
Tonga	TO
Trinidad and Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Tuvalu	TV
U.S. Virgin Islands	VI
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States	US
Uruguay	UY
Uzbekistan	UZ
Vanuatu	VU
Vatican City	VA
Venezuela	VE
Vietnam	VN
Yemen	YE
Zambia	ZM
Zimbabwe	ZW
Kosovo	XK
South Sudan	SS
China	CN
Palestine	PS
Curacao	CW
Dominican Republic	DO
Dominican Republic	DO
Gibraltar	GI
New Caledonia	NC
Cook Islands	CK
Reunion	RE
Guernsey	GG
Guadeloupe	GP
Martinique	MQ
French Polynesia	PF
Faroe Islands	FO
Greenland	GL
Jersey	JE
Aruba	AW
Puerto Rico	PR
Isle of Man	IM
Guam	GU
Sint Maarten	SX
Turks and Caicos	TC
Åland Islands	AX
Caribbean Netherlands	BQ
British Indian Ocean Territory	IO
Christmas as Island	CX
Cocos (Keeling) Islands	CC
Falkland Islands (Islas Malvinas)	FK
Mayotte	YT
Niue	NU
Norfolk Island	NF
Northern Mariana Islands	MP
Pitcairn Islands	PN
Saint Helena, Ascension and Tristan da Cunha	SH
Collectivity of Saint Martin	MF
Saint Pierre and Miquelon	PM
Tokelau	TK
Wallis and Futuna	WF
American Samoa	AS

Cancel withdrawal

You can cancel normal withdrawal requests, but you cannot cancel withdrawal requests on Lightning.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/cancel-withdrawal

Request Example

POST /api/v5/asset/cancel-withdrawal
body {
   "wdId":"1123456"
}

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Cancel withdrawal
result = fundingAPI.cancel_withdrawal(
    wdId="123456"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
wdId	String	Yes	Withdrawal ID

Response Example

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

Response Parameters

Parameter	Type	Description
wdId	String	Withdrawal ID

Get withdrawal history

Retrieve the withdrawal records according to the currency, withdrawal status, and time range in reverse chronological order. The 100 most recent records are returned by default.
Websocket API is also available, refer to Withdrawal info channel.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/withdrawal-history

Request Example


GET /api/v5/asset/withdrawal-history

# Query withdrawal history from 2022-06-01 to 2022-07-01
GET /api/v5/asset/withdrawal-history?ccy=BTC&after=1654041600000&before=1656633600000

Request Parameters

Parameter	Type	Required	Description
ccy	String	No	Currency, e.g. `BTC`
wdId	String	No	Withdrawal ID
clientId	String	No	Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
txId	String	No	Hash record of the deposit
type	String	No	Withdrawal type `3`: Internal transfer `4`: On-chain withdrawal
state	String	No	Status of withdrawal Stage 1 : Pending withdrawal `10`: Waiting transfer `0`: Waiting withdrawal `4`/`5`/`6`/`8`/`9`/`12`: Waiting manual review `7`: Approved Stage 2 : Withdrawal in progress (Applicable to on-chain withdrawals, internal transfers do not have this stage) `1`: Broadcasting your transaction to chain `15`: Pending transaction validation `16`: Due to local laws and regulations, your withdrawal may take up to 24 hours to arrive `-3`: Canceling Final stage `-2`: Canceled `-1`: Failed `2`: Success
after	String	No	Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. `1654041600000`
before	String	No	Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. `1656633600000`
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "chain": "ETH-Ethereum",
      "fee": "0.007",
      "ccy": "ETH",
      "clientId": "",
      "amt": "0.029809",
      "txId": "0x35c******b360a174d",
      "from": "156****359",
      "areaCodeFrom": "86",
      "to": "0xa30d1fab********7CF18C7B6C579",
      "areaCodeTo": "",
      "state": "2",
      "ts": "1655251200000",
      "wdId": "15447421"
    }
  ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
chain	String	Chain name, e.g. `USDT-ERC20`, `USDT-TRC20`
nonTradableAsset	Boolean	Whether it is a non-tradable asset or not `true`: non-tradable asset, `false`: tradable asset
amt	String	Withdrawal amount
ts	String	Time the withdrawal request was submitted, Unix timestamp format in milliseconds, e.g. `1655251200000`.
from	String	Withdrawal account It can be `email`/`phone`/`sub-account name`
areaCodeFrom	String	Area code for the phone number If `from` is a phone number, this parameter returns the area code for the phone number
to	String	Receiving address
areaCodeTo	String	Area code for the phone number If `to` is a phone number, this parameter returns the area code for the phone number
tag	String	Some currencies require a tag for withdrawals. This is not returned if not required.
pmtId	String	Some currencies require a payment ID for withdrawals. This is not returned if not required.
memo	String	Some currencies require this parameter for withdrawals. This is not returned if not required.
addrEx	Object	Withdrawal address attachment (This will not be returned if the currency does not require this) e.g. TONCOIN attached tag name is comment, the return will be {'comment':'123456'}
txId	String	Hash record of the withdrawal This parameter will return "" for internal transfers.
fee	String	Withdrawal fee amount
feeCcy	String	Withdrawal fee currency, e.g. `USDT`
state	String	Status of withdrawal
wdId	String	Withdrawal ID
clientId	String	Client-supplied ID

Get deposit withdraw status

Retrieve deposit's and withdrawal's detailed status and estimated complete time.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-withdraw-status

Request Example

# For deposit
GET /api/v5/asset/deposit-withdraw-status?txId=xxxxxx&to=1672734730284&ccy=USDT&chain=USDT-ERC20

# For withdrawal
GET /api/v5/asset/deposit-withdraw-status?wdId=200045249

Request Parameters

Parameters	Types	Required	Description
wdId	String	Conditional	Withdrawl ID, use to retrieve withdrawal status Required to input one and only one of `wdId` and `txId`
txId	String	Conditional	Hash record of the deposit, use to retrieve deposit status Required to input one and only one of `wdId` and `txId`
ccy	String	Conditional	Currency type, e.g. `USDT` Required when retrieving deposit status with `txId`
to	String	Conditional	To address, the destination address in deposit Required when retrieving deposit status with `txId`
chain	String	Conditional	Currency chain infomation, e.g. USDT-ERC20 Required when retrieving deposit status with `txId`

Response Example

{
    "code":"0",
    "data":[
        {
            "wdId": "200045249",
            "txId": "16f3638329xxxxxx42d988f97", 
            "state": "Pending withdrawal: Wallet is under maintenance, please wait.",
            "estCompleteTime": "01/09/2023, 8:10:48 PM"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
estCompleteTime	String	Estimated complete time The timezone is UTC+8. The format is MM/dd/yyyy, h:mm:ss AM/PM estCompleteTime is only an approximate estimated time, for reference only.
state	String	The detailed stage and status of the deposit/withdrawal The message in front of the colon is the stage; the message after the colon is the ongoing status.
txId	String	Hash record on-chain For withdrawal, if the `txId` has already been generated, it will return the value, otherwise, it will return "".
wdId	String	Withdrawal ID When retrieving deposit status, wdId returns blank "".

Small assets convert

Convert small assets in funding account to OKB. Only 5 convert is allowed within 24 hours.

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/convert-dust-assets

Request Example

POST /api/v5/asset/convert-dust-assets
body {
   "ccy":["BTC","USDT"]
}

import okx.Funding as Funding

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "0"  # Production trading: 0, Demo trading: 1

fundingAPI = Funding.FundingAPI(apikey, secretkey, passphrase, False, flag)

# Small assets convert
result = fundingAPI.convert_dust_assets(
    ccy=["BTC","USDT"]
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	Array of strings	Yes	Small assets needed to be converted, e.g. ["BTC","USDT"]

Response Example

{
  "code": "0",
  "data": [
    {
      "details": [
        {
          "amt": "1",
          "ccy": "USDT",
          "cnvAmt": "0.04771642808422",
          "fee": "0.00097380465478"
        }
      ],
      "totalCnvAmt": "0.04771642"
    }
  ],
  "msg": ""
}

Response Parameters

Parameter	Type	Description
totalCnvAmt	String	Total quantity of `OKB` after conversion
details	Array of objects	Details of asset conversion
> ccy	String	Currency, e.g. `BTC`
> amt	String	Quantity of currency assets before conversion
> cnvAmt	String	Quantity of `OKB` after conversion
> fee	String	Fee for conversion, unit in `OKB`

Get exchange list (public)

Authentication is not required for this public endpoint.

Rate Limit: 6 requests per second

Rate limit rule: IP

HTTP Request

GET /api/v5/asset/exchange-list

Request Example

GET /api/v5/asset/exchange-list

Request Parameters

None

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "exchId": "did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1",
        "exchName": "1xbet"
    }
  ]
}

Response Parameters

Parameter	Type	Description
exchName	String	Exchange name, e.g. `1xbet`
exchId	String	Exchange ID, e.g. `did:ethr:0xfeb4f99829a9acdf52979abee87e83addf22a7e1`

Apply for monthly statement (last year)

Apply for monthly statement in the past year.

Rate Limit: 20 requests per month

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/monthly-statement

Request Example

POST /api/v5/asset/monthly-statement
body
{
    "month":"Jan"
}

Request Parameters

Parameter	Type	Required	Description
month	String	No	Month,last month by default. Valid value is `Jan`, `Feb`, `Mar`, `Apr`,`May`, `Jun`, `Jul`,`Aug`, `Sep`,`Oct`,`Nov`,`Dec`

Response Example

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

Response Parameters

Parameter	Type	Description
ts	String	Download link generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

GET monthly statement (last year)

Retrieve monthly statement in the past year.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/monthly-statement

Request Example

GET /api/v5/asset/monthly-statement?month=Jan

Request Parameters

Parameter	Type	Required	Description
month	String	Yes	Month, valid value is `Jan`, `Feb`, `Mar`, `Apr`,`May`, `Jun`, `Jul`,`Aug`, `Sep`,`Oct`,`Nov`,`Dec`

Response Example

{
    "code": "0",
    "data": [
        {
            "fileHref": "http://xxx",
            "state": "finished",
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
fileHref	String	Download file link
ts	String	Download link generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
state	String	Download link status "finished" "ongoing"

Get convert currencies

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/convert/currencies

Request Example

GET /api/v5/asset/convert/currencies

Response parameters

none

Response Example

{
    "code": "0",
    "data": [
        {
            "min": "",  // Deprecated
            "max": "",  // Deprecated
            "ccy": "BTC"
        },
        {
            "min": "",
            "max": "",
            "ccy": "ETH"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency, e.g. BTC
min	String	Minimum amount to convert ( Deprecated )
max	String	Maximum amount to convert ( Deprecated )

Get convert currency pair

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/convert/currency-pair

Request Example

GET /api/v5/asset/convert/currency-pair?fromCcy=USDT&toCcy=BTC

Response parameters

Parameters	Types	Required	Description
fromCcy	String	Yes	Currency to convert from, e.g. `USDT`
toCcy	String	Yes	Currency to convert to, e.g. `BTC`

Response Example

{
    "code": "0",
    "data": [
        {
            "baseCcy": "BTC",
            "baseCcyMax": "0.5",
            "baseCcyMin": "0.0001",
            "instId": "BTC-USDT",
            "quoteCcy": "USDT",
            "quoteCcyMax": "10000",
            "quoteCcyMin": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instId	String	Currency pair, e.g. `BTC-USDT`
baseCcy	String	Base currency, e.g. `BTC` in `BTC-USDT`
baseCcyMax	String	Maximum amount of base currency
baseCcyMin	String	Minimum amount of base currency
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT`
quoteCcyMax	String	Maximum amount of quote currency
quoteCcyMin	String	Minimum amount of quote currency

Estimate quote

Rate Limit: 10 requests per second

Rate limit rule: UserID

Rate Limit: 1 request per 5 seconds

Rate limit rule: Instrument

HTTP Request

POST /api/v5/asset/convert/estimate-quote

Request Example

POST /api/v5/asset/convert/estimate-quote
body
{
    "baseCcy": "ETH",
    "quoteCcy": "USDT",
    "side": "buy",
    "rfqSz": "30",
    "rfqSzCcy": "USDT"
}

Request Parameters

Parameters	Types	Required	Description
baseCcy	String	Yes	Base currency, e.g. `BTC` in `BTC-USDT`
quoteCcy	String	Yes	Quote currency, e.g. `USDT` in `BTC-USDT`
side	String	Yes	Trade side based on `baseCcy` `buy` `sell`
rfqSz	String	Yes	RFQ amount
rfqSzCcy	String	Yes	RFQ currency
clQReqId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag	String	No	Order tag Applicable to broker user

Response Example

{
    "code": "0",
    "data": [
        {
            "baseCcy": "ETH",
            "baseSz": "0.01023052",
            "clQReqId": "",
            "cnvtPx": "2932.40104429",
            "origRfqSz": "30",
            "quoteCcy": "USDT",
            "quoteId": "quoterETH-USDT16461885104612381",
            "quoteSz": "30",
            "quoteTime": "1646188510461",
            "rfqSz": "30",
            "rfqSzCcy": "USDT",
            "side": "buy",
            "ttlMs": "10000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
quoteTime	String	Quotation generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
ttlMs	String	Validity period of quotation in milliseconds
clQReqId	String	Client Order ID as assigned by the client
quoteId	String	Quote ID
baseCcy	String	Base currency, e.g. `BTC` in `BTC-USDT`
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT`
side	String	Trade side based on `baseCcy`
origRfqSz	String	Original RFQ amount
rfqSz	String	Real RFQ amount
rfqSzCcy	String	RFQ currency
cnvtPx	String	Convert price based on quote currency
baseSz	String	Convert amount of base currency
quoteSz	String	Convert amount of quote currency

Convert trade

You should make estimate quote before convert trade.

Rate Limit: 10 requests per second

Rate limit rule: UserID

For the same side (buy/sell), there's a trading limit of 1 request per 5 seconds.

HTTP Request

POST /api/v5/asset/convert/trade

Request Example

POST /api/v5/asset/convert/trade
body
{
    "baseCcy": "ETH",
    "quoteCcy": "USDT",
    "side": "buy",
    "sz": "30",
    "szCcy": "USDT",
    "quoteId": "quoterETH-USDT16461885104612381"
}

Request Parameters

Parameters	Types	Required	Description
quoteId	String	Yes	Quote ID
baseCcy	String	Yes	Base currency, e.g. `BTC` in `BTC-USDT`
quoteCcy	String	Yes	Quote currency, e.g. `USDT` in `BTC-USDT`
side	String	Yes	Trade side based on `baseCcy` `buy` `sell`
sz	String	Yes	Quote amount The quote amount should no more then RFQ amount
szCcy	String	Yes	Quote currency
clTReqId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag	String	No	Order tag Applicable to broker user

Response Example

{
    "code": "0",
    "data": [
        {
            "baseCcy": "ETH",
            "clTReqId": "",
            "fillBaseSz": "0.01023052",
            "fillPx": "2932.40104429",
            "fillQuoteSz": "30",
            "instId": "ETH-USDT",
            "quoteCcy": "USDT",
            "quoteId": "quoterETH-USDT16461885104612381",
            "side": "buy",
            "state": "fullyFilled",
            "tradeId": "trader16461885203381437",
            "ts": "1646188520338"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
tradeId	String	Trade ID
quoteId	String	Quote ID
clTReqId	String	Client Order ID as assigned by the client
state	String	Trade state `fullyFilled`: success `rejected`: failed
instId	String	Currency pair, e.g. `BTC-USDT`
baseCcy	String	Base currency, e.g. `BTC` in `BTC-USDT`
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT`
side	String	Trade side based on `baseCcy` `buy` `sell`
fillPx	String	Filled price based on quote currency
fillBaseSz	String	Filled amount for base currency
fillQuoteSz	String	Filled amount for quote currency
ts	String	Convert trade time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get convert history

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/convert/history

Request Example

GET /api/v5/asset/convert/history

Request Parameters

Parameters	Types	Required	Description
clTReqId	String	No	Client Order ID as assigned by the client A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
after	String	No	Pagination of data to return records earlier than the requested `ts`, Unix timestamp format in milliseconds, e.g. `1597026383085`
before	String	No	Pagination of data to return records newer than the requested `ts`, Unix timestamp format in milliseconds, e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is `100`. The default is `100`.
tag	String	No	Order tag Applicable to broker user If the convert trading used `tag`, this parameter is also required.

Response Example

{
    "code": "0",
    "data": [
        {
            "clTReqId": "",
            "instId": "ETH-USDT",
            "side": "buy",
            "fillPx": "2932.401044",
            "baseCcy": "ETH",
            "quoteCcy": "USDT",
            "fillBaseSz": "0.01023052",
            "state": "fullyFilled",
            "tradeId": "trader16461885203381437",
            "fillQuoteSz": "30",
            "ts": "1646188520000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
tradeId	String	Trade ID
clTReqId	String	Client Order ID as assigned by the client
state	String	Trade state `fullyFilled` : success `rejected` : failed
instId	String	Currency pair, e.g. `BTC-USDT`
baseCcy	String	Base currency, e.g. `BTC` in `BTC-USDT`
quoteCcy	String	Quote currency, e.g. `USDT` in `BTC-USDT`
side	String	Trade side based on `baseCcy` `buy` `sell`
fillPx	String	Filled price based on quote currency
fillBaseSz	String	Filled amount for base currency
fillQuoteSz	String	Filled amount for quote currency
ts	String	Convert trade time, Unix timestamp format in milliseconds, e.g. `1597026383085`

WebSocket

Deposit info channel

A push notification is triggered when a deposit is initiated or the deposit status changes.
Supports subscriptions for accounts

If it is a master account subscription, you can receive the push of the deposit info of both the master account and the sub-account.
If it is a sub-account subscription, only the push of sub-account deposit info you can receive.

URL Path

/ws/v5/business (required login)

Request Example

{
    "op": "subscribe",
    "args": [
        {
            "channel": "deposit-info"
        }
    ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `deposit-info`
> ccy	String	No	Currency, e.g. `BTC`

Successful Response Example

{
    "event": "subscribe",
    "arg": {
        "channel": "deposit-info"
    },
    "connId": "a4d3ae55"
}

Failure Response Example

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"deposit-info\""}]}",
    "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Operation `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name `deposit-info`
> ccy	String	No	Currency, e.g. `BTC`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "deposit-info",
        "uid": "289320****60975104"
    },
    "data": [{
        "actualDepBlkConfirm": "0",
        "amt": "1",
        "areaCodeFrom": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "depId": "88165462",
        "from": "",
        "fromWdId": "",
        "pTime": "1674103661147",
        "state": "0",
        "subAcct": "test",
        "to": "TEhFAqpuHa3LY*****8ByNoGnrmexeGMw",
        "ts": "1674103661123",
        "txId": "bc5376817*****************dbb0d729f6b",
        "uid": "289320****60975104"
    }]
}

Push data parameters

Parameters	Types	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> uid	String	User Identifier
> ccy	String	Currency, e.g. `BTC`
data	Array	Subscribed data
> uid	String	User Identifier of the message producer
> subAcct	String	Sub-account name If the message producer is master account, the parameter will return ""
> pTime	String	Push time, the millisecond format of the Unix timestamp, e.g. `1597026383085`
> ccy	String	Currency
> chain	String	Chain name
> amt	String	Deposit amount
> from	String	Deposit account Only the internal Turkey account is returned, not the address on the blockchain.
> areaCodeFrom	String	If `from` is a phone number, this parameter return area code of the phone number
> to	String	Deposit address
> txId	String	Hash record of the deposit
> ts	String	Time of deposit record is created, Unix timestamp format in milliseconds, e.g. `1655251200000`
> state	String	Status of deposit `0`: waiting for confirmation `1`: deposit credited `2`: deposit successful `8`: pending due to temporary deposit suspension on this crypto currency `11`: match the address blacklist `12`: account or deposit is frozen `13`: sub-account deposit interception `14`: KYC limit
> depId	String	Deposit ID
> fromWdId	String	Internal transfer initiator's withdrawal ID If the deposit comes from internal transfer, this field displays the withdrawal ID of the internal transfer initiator, and will return "" in other cases
> actualDepBlkConfirm	String	The actual amount of blockchain confirmed in a single deposit

Withdrawal info channel

A push notification is triggered when a withdrawal is initiated or the withdrawal status changes.
Supports subscriptions for accounts

If it is a master account subscription, you can receive the push of the withdrawal info of both the master account and the sub-account.
If it is a sub-account subscription, only the push of sub-account withdrawal info you can receive.

URL Path

/ws/v5/business (required login)

Request Example

{
    "op": "subscribe",
    "args": [
        {
            "channel": "withdrawal-info"
        }
    ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	Operation `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `withdrawal-info`
> ccy	String	No	Currency, e.g. `BTC`

Successful Response Example

{
    "event": "subscribe",
    "arg": {
        "channel": "withdrawal-info"
    },
    "connId": "a4d3ae55"
}

Failure Response Example

{
    "event": "error",
    "code": "60012",
    "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"withdrawal-info\"}]}",
    "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Operation `subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name `withdrawal-info`
> ccy	String	No	Currency, e.g. `BTC`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "withdrawal-info",
        "uid": "289320*****0975104"
    },
    "data": [{
        "addrEx": null,
        "amt": "2",
        "areaCodeFrom": "",
        "areaCodeTo": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "clientId": "",
        "fee": "0.8",
        "feeCcy": "USDT",
        "from": "",
        "memo": "",
        "nonTradableAsset": false,
        "pTime": "1674103268578",
        "pmtId": "",
        "state": "0",
        "subAcct": "test",
        "tag": "",
        "to": "TN8CKTQMnpWfT******8KipbJ24ErguhF",
        "ts": "1674103268472",
        "txId": "",
        "uid": "289333*****1101696",
        "wdId": "63754560"
    }]
}

Push data parameters

Parameters	Types	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
> uid	String	User Identifier
> ccy	String	Currency, e.g. `BTC`
data	Array	Subscribed data
> uid	String	User Identifier of the message producer
> subAcct	String	Sub-account name If the message producer is master account, the parameter will return ""
> pTime	String	Push time, the millisecond format of the Unix timestamp, e.g. `1597026383085`
> ccy	String	Currency
> chain	String	Chain name, e.g. `USDT-ERC20`, `USDT-TRC20`
> nonTradableAsset	String	Whether it is a non-tradable asset or not `true`: non-tradable asset, `false`: tradable asset
> amt	String	Withdrawal amount
> ts	String	Time the withdrawal request was submitted, Unix timestamp format in milliseconds, e.g. `1655251200000`.
> from	String	Withdrawal account It can be `email`/`phone`/`sub-account name`
> areaCodeFrom	String	Area code for the phone number If `from` is a phone number, this parameter returns the area code for the phone number
> to	String	Receiving address
> areaCodeTo	String	Area code for the phone number If `to` is a phone number, this parameter returns the area code for the phone number
> tag	String	Some currencies require a tag for withdrawals
> pmtId	String	Some currencies require a payment ID for withdrawals
> memo	String	Some currencies require this parameter for withdrawals
> addrEx	Object	Withdrawal address attachment, e.g. `TONCOIN` attached tag name is comment, the return will be {'comment':'123456'}
> txId	String	Hash record of the withdrawal This parameter will return "" for internal transfers.
> fee	String	Withdrawal fee amount
> feeCcy	String	Withdrawal fee currency, e.g. `USDT`
> state	String	Status of withdrawal Stage 1 : Pending withdrawal `10`: Waiting transfer `0`: Waiting withdrawal `4`/`5`/`6`/`8`/`9`/`12`: Waiting manual review `7`: Approved Stage 2 : Withdrawal in progress (Applicable to on-chain withdrawals, internal transfers do not have this stage) `1`: Broadcasting your transaction to chain `15`: Pending transaction validation `16`: Due to local laws and regulations, your withdrawal may take up to 24 hours to arrive `-3`: Canceling Final stage `-2`: Canceled `-1`: Failed `2`: Success
> wdId	String	Withdrawal ID
> clientId	String	Client-supplied ID

Sub-account

The API endpoints of sub-account require authentication.

REST API

Get sub-account list

Applies to master accounts only

Rate limit：2 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/users/subaccount/list

Request sample

GET /api/v5/users/subaccount/list

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account list
result = subAccountAPI.get_subaccount_list()
print(result)

Request Parameters

Parameter	Type	Required	Description
enable	String	No	Sub-account status `true`: Normal `false`: Frozen
subAcct	String	No	Sub-account name
after	String	No	Query the data earlier than the requested subaccount creation timestamp, the value should be a Unix timestamp in millisecond format. e.g. `1597026383085`
before	String	No	Query the data newer than the requested subaccount creation timestamp, the value should be a Unix timestamp in millisecond format. e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is 100. The default is 100.

Returned results

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "canTransOut": false,
            "enable": true,
            "frozenFunc": [
            ],
            "gAuth": false,
            "label": "D456DDDLx",
            "mobile": "",
            "subAcct": "D456DDDL",
            "ts": "1659334756000",
            "type": "1",
            "uid": "3400***********7413"
        }
    ]
}

Response parameters

Parameter name	Type	Description
type	String	Sub-account type `1`: Standard sub-account `2`: Managed trading sub-account `5`: Custody sub-account - Copper
enable	Boolean	Sub-account status `true`: Normal `false`: Frozen (global)
subAcct	String	Sub-account name
uid	String	Sub-account uid
label	String	Sub-account note
mobile	String	Mobile number that linked with the sub-account.
gAuth	Boolean	If the sub-account switches on the Google Authenticator for login authentication. `true`: On `false`: Off
frozenFunc	Array of string	Frozen functions `trading` `convert` `transfer` `withdrawal` `deposit` `flexible_loan`
canTransOut	Boolean	Whether the sub-account has the right to transfer out. `true`: can transfer out `false`: cannot transfer out
ts	String	Sub-account creation time, Unix timestamp in millisecond format. e.g. `1597026383085`

Reset the API Key of a sub-account

Applies to master accounts only and master accounts API Key must be linked to IP addresses. Only API keys with Trade privilege can call this endpoint.

Rate limit：1 request per second

Rate limit rule: UserID

HTTP request

POST /api/v5/users/subaccount/modify-apikey

Request sample

POST /api/v5/users/subaccount/modify-apikey
body
{
    "subAcct":"yongxu",
    "apiKey":"49e1b84b-6dee-4894-80ee-ce9eb7ad614f",
    "ip":"1.1.1.1"
}

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Reset the API Key of a sub-account
result = subAccountAPI.reset_subaccount_apikey(
    subAcct="hahawang1",
    apiKey="",
    ip=""
)
print(result)

Request Parameters

Parameter name	Type	Required	Description
subAcct	String	Yes	Sub-account name
apiKey	String	Yes	Sub-account APIKey
label	String	No	Sub-account API Key label. The label will be reset if this is passed through.
perm	String	No	Sub-account API Key permissions `read_only`: Read `trade`: Trade Separate with commas if more than one. The permission will be reset if this is passed through.
ip	String	No	Sub-account API Key linked IP addresses, separate with commas if more than one. Support up to 20 IP addresses. The IP will be reset if this is passed through. If `ip` is set to "", then no IP addresses is linked to the APIKey.

Returned results

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "yongxu",
        "label": "v5",
        "apiKey": "arg13sdfgs",
        "perm": "read,trade",
        "ip": "1.1.1.1",
        "ts": "1597026383085"
    }]
}

Response parameters

Parameter name	Type	Description
subAcct	String	Sub-account name
apiKey	String	Sub-accountAPI public key
label	String	Sub-account API Key label
perm	String	Sub-account API Key permissions `read_only`: Read `trade`: Trade
ip	String	Sub-account API Key IP addresses that linked with API Key
ts	String	Creation time

Get sub-account trading balance

Query detailed balance info of Trading Account of a sub-account via the master account (applies to master accounts only)

Rate limit：6 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/account/subaccount/balances

Request sample

GET /api/v5/account/subaccount/balances?subAcct=test1

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account trading balance
result = subAccountAPI.get_account_balance(
    subAcct="hahawang1"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
subAcct	String	Yes	Sub-account name

Returned result

{
    "code": "0",
    "data": [
        {
            "adjEq": "10679688.0460531643092577",
            "borrowFroz": "",
            "details": [
                {
                    "availBal": "",
                    "availEq": "9930359.9998",
                    "cashBal": "9930359.9998",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "9439737.0772999514",
                    "eq": "9930359.9998",
                    "eqUsd": "9933041.196999946",
                    "smtSyncEq": "0",
                    "fixedBal": "0",
                    "frozenBal": "0",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0",
                    "borrowFroz": "",
                    "spotIsoBal": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "smtSyncEq": "0",
                    "fixedBal": "0",
                    "frozenBal": "0.0918492093160816",
                    "imr": "",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "mmr": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0",
                    "borrowFroz": "",
                    "spotIsoBal": "0",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718",
            "upl": "-7.571730042000012"
        }
    ],
    "msg": ""
}

Response parameters

Parameters	Types	Description
uTime	String	The latest time to get account information, millisecond format of Unix timestamp, e.g. `1597026383085`
totalEq	String	The total amount of equity in `USD`
isoEq	String	Isolated margin equity in `USD` Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
adjEq	String	Adjusted / Effective equity in `USD` The net fiat value of the assets in the account that can provide margins for spot, expiry futures, perpetual futures and options under the cross-margin mode. In multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation. Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks. Applicable to `Multi-currency margin`/`Portfolio margin`
ordFroz	String	Margin frozen for pending cross orders in `USD` Applicable to `Multi-currency margin`
imr	String	Initial margin requirement in `USD` The sum of initial margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Multi-currency margin`/`Portfolio margin`
mmr	String	Maintenance margin requirement in `USD` The sum of maintenance margins of all open positions and pending orders under cross-margin mode in `USD`. Applicable to `Multi-currency margin`/`Portfolio margin`
borrowFroz	String	Potential borrowing IMR of the account in `USD` Only applicable to `Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
mgnRatio	String	Margin ratio in `USD`. Applicable to `Multi-currency margin`/`Portfolio margin`
notionalUsd	String	Notional value of positions in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
upl	String	Cross-margin info of unrealized profit and loss at the account level in `USD` Applicable to `Multi-currency margin`/`Portfolio margin`
details	Array	Detailed asset information in all currencies
> ccy	String	Currency
> eq	String	Equity of currency
> cashBal	String	Cash Balance
> uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> isoEq	String	Isolated margin equity of currency Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> fixedBal	String	Frozen balance for `Dip Sniper` and `Peak Sniper`
> availEq	String	Available equity of currency The balance that can be used on margin or futures/swap trading. Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> disEq	String	Discount equity of currency in `USD`
> availBal	String	Available balance of currency
> frozenBal	String	Frozen balance of currency
> ordFrozen	String	Margin frozen for open orders Applicable to `Spot mode`/`Spot and futures mode`/`Multi-currency margin`
> liab	String	Liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> upl	String	The sum of the unrealized profit & loss of all margin and derivatives positions of currency. Applicable to `Spot and futures mode`/`Multi-currency margin`/`Portfolio margin`
> uplLiab	String	Liabilities due to Unrealized loss of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> crossLiab	String	Cross Liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> isoLiab	String	Isolated Liabilities of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> mgnRatio	String	Cross margin ratio of currency The index for measuring the risk of a certain asset in the account. Applicable to `Spot and futures mode` and when there is cross position
> imr	String	Cross initial margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
> mmr	String	Cross maintenance margin requirement at the currency level Applicable to `Spot and futures mode` and when there is cross position
> interest	String	Interest of currency Applicable to `Multi-currency margin`/`Portfolio margin`
> twap	String	System's forced repayment(TWAP) indicator Divided into multiple levels from 0 to 5, the larger the number, the more likely the auto repayment will be triggered. Applicable to `Multi-currency margin`/`Portfolio margin`
> maxLoan	String	Max loan of currency Applicable to `cross` of `Multi-currency margin`/`Portfolio margin`
> eqUsd	String	Equity `USD` of currency
> borrowFroz	String	Potential borrowing IMR of currency in `USD` Only applicable to `Multi-currency margin`/`Portfolio margin`. It is "" for other margin modes.
> notionalLever	String	Leverage of currency Applicable to `Spot and futures mode`
> spotIsoBal	String	SPOT isolated balance. only applicable to copy trading
> smtSyncEq	String	Smark sync equity The default is "0", only applicable to copy trader
> spotBal	String	Spot balance. The unit is currency, e.g. BTC. Clicking knows more
> openAvgPx	Array	Spot average cost price. The unit is USD. Clicking knows more
> accAvgPx	Array	Spot accumulated cost price. The unit is USD. Clicking knows more
> spotUpl	String	Spot unrealized profit and loss. The unit is USD. Clicking knows more
> spotUplRatio	String	Spot unrealized profit and loss ratio. Clicking knows more
> totalPnl	String	Spot accumulated profit and loss. The unit is USD. Clicking knows more
> totalPnlRatio	String	Spot accumulated profit and loss ratio. Clicking knows more

Get sub-account funding balance

Query detailed balance info of Funding Account of a sub-account via the master account (applies to master accounts only)

Rate limit：6 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/asset/subaccount/balances

Request sample

GET /api/v5/asset/subaccount/balances?subAcct=test1

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account funding balance
result = subAccountAPI.get_funding_balance(
    subAcct="hahawang1"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
subAcct	String	Yes	Sub-account name
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Returned result

{
    "code": "0",
    "msg": "",
    "data": [{
            "availBal": "37.11827078",
            "bal": "37.11827078",
            "ccy": "ETH",
            "frozenBal": "0"
        }
    ]
}

Response parameters

Parameter	Type	Description
ccy	String	Currency
bal	String	Balance
frozenBal	String	Frozen balance
availBal	String	Available balance

Get sub-account maximum withdrawals

Retrieve the maximum withdrawal information of a sub-account via the master account (applies to master accounts only). If no currency is specified, the transferable amount of all owned currencies will be returned.

Rate limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/account/subaccount/max-withdrawal

Request Example

GET /api/v5/account/subaccount/max-withdrawal?subAcct=test1

Request Parameters

Parameter	Type	Required	Description
subAcct	String	Yes	Sub-account name
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Response Example

{
   "code":"0",
   "data":[
      {
         "ccy":"BTC",
         "maxWd":"3",
         "maxWdEx":"",
         "spotOffsetMaxWd":"3",
         "spotOffsetMaxWdEx":""
      },
      {
         "ccy":"ETH",
         "maxWd":"15",
         "maxWdEx":"",
         "spotOffsetMaxWd":"15",
         "spotOffsetMaxWdEx":""
      },
      {
         "ccy":"USDT",
         "maxWd":"10600",
         "maxWdEx":"",
         "spotOffsetMaxWd":"10600",
         "spotOffsetMaxWdEx":""
      }
   ],
   "msg":""
}

Response parameters

Parameter	Type	Description
ccy	String	Currency
maxWd	String	Max withdrawal (excluding borrowed assets under `Multi-currency margin`)
maxWdEx	String	Max withdrawal (including borrowed assets under `Multi-currency margin`)
spotOffsetMaxWd	String	Max withdrawal under Spot-Derivatives risk offset mode (excluding borrowed assets under `Portfolio margin`) Applicable to `Portfolio margin`
spotOffsetMaxWdEx	String	Max withdrawal under Spot-Derivatives risk offset mode (including borrowed assets under `Portfolio margin`) Applicable to `Portfolio margin`

Get history of sub-account transfer

Applies to master accounts only.

Rate limit：6 requests per second

Rate limit rule: UserID

HTTP request

GET /api/v5/asset/subaccount/bills

Request sample

GET /api/v5/asset/subaccount/bills

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Get history of sub-account transfer
result = subAccountAPI.bills()
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	No	Currency, such as BTC
type	String	No	Transfer type `0`: Transfers from master account to sub-account `1` : Transfers from sub-account to master account.
subAcct	String	No	Sub-account name
after	String	No	Query the data prior to the requested bill ID creation time (exclude), the value should be a Unix timestamp in millisecond format. e.g. `1597026383085`
before	String	No	Query the data after the requested bill ID creation time (exclude), the value should be a Unix timestamp in millisecond format. e.g. `1597026383085`
limit	String	No	Number of results per request. The maximum is 100. The default is 100.

Returned results

{
    "code": "0",
    "msg": "",
    "data": [
      {
        "amt": "1.1",
        "billId": "89887685",
        "ccy": "USDT", 
        "subAcct": "hahatest1",
        "ts": "1712560959000",
        "type": "0"
      }
    ]
}

Response parameters

Parameter name	Type	Description
billId	String	Bill ID
ccy	String	Transfer currency
amt	String	Transfer amount
type	String	Bill type
subAcct	String	Sub-account name
ts	String	Bill ID creation time, Unix timestamp in millisecond format, e.g. `1597026383085`

Master accounts manage the transfers between sub-accounts

Applies to master accounts only.

Only API keys with Trade privilege can call this endpoint.

Rate limit：1 request per second

Rate limit rule: UserID

HTTP request

POST /api/v5/asset/subaccount/transfer

Request sample

POST /api/v5/asset/subaccount/transfer
body
{
    "ccy":"USDT",
    "amt":"1.5",
    "from":"6",
    "to":"6",
    "fromSubAccount":"test-1",
    "toSubAccount":"test-2"
}

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Master accounts manage the transfers between sub-accounts
result = subAccountAPI.subAccount_transfer(
    ccy="USDT",
    amt="10",
    froms="6",
    to="6",
    fromSubAccount="test-1",
    toSubAccount="test-2"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
ccy	String	Yes	Currency
amt	String	Yes	Transfer amount
from	String	Yes	Account type of transfer from sub-account `6`: Funding Account `18`: Trading account
to	String	Yes	Account type of transfer to sub-account `6`: Funding Account `18`: Trading account
fromSubAccount	String	Yes	Sub-account name of the account that transfers funds out.
toSubAccount	String	Yes	Sub-account name of the account that transfers funds in.
loanTrans	Boolean	No	Whether or not borrowed coins can be transferred out under `Multi-currency margin`/`Portfolio margin` The default is `false`
omitPosRisk	String	No	Ignore position risk Default is `false` Applicable to `Portfolio margin`

Returned results

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

Response parameters

Parameter name	Type	Description
transId	String	Transfer ID

Set permission of transfer out

Set permission of transfer out for sub-account (only applicable to master account API key). Sub-account can transfer out to master account by default.

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/users/subaccount/set-transfer-out

Request Example

POST /api/v5/users/subaccount/set-transfer-out
body
{
    "subAcct": "Test001,Test002",
    "canTransOut": true
}

import okx.SubAccount as SubAccount

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"

flag = "1"  # Production trading: 0, Demo trading: 1

subAccountAPI = SubAccount.SubAccountAPI(apikey, secretkey, passphrase, False, flag)

# Set permission of transfer out for sub-account
result = subAccountAPI.set_permission_transfer_out(
    subAcct="hahawang1",
    canTransOut=False
)
print(result)

Request Parameters

Parameter	Type	Required	Description
subAcct	String	Yes	Name of the sub-account. Single sub-account or multiple sub-account (no more than 20) separated with comma.
canTransOut	Boolean	No	Whether the sub-account has the right to transfer out. The default is `true`. `false`: cannot transfer out `true`: can transfer out

Returned result

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "subAcct": "Test001",
            "canTransOut": true
        },
        {
            "subAcct": "Test002",
            "canTransOut": true
        }
    ]
}

Response parameters

Parameter	Type	Description
subAcct	String	Name of the sub-account
canTransOut	Boolean	Whether the sub-account has the right to transfer out. `false`: cannot transfer out `true`: can transfer out

Affiliate

The Affiliate API offers affiliate users a flexible function to query the invitee information. Simply enter the UID of your direct invitee to access their relevant information, empowering your affiliate business growth and day-to-day business operation. If you have additional data requirements regarding the Affiliate API, please don't hesitate to contact your BD. We will reach out to you through your BD to provide more comprehensive API support.

REST API

Get the invitee's detail

Rate limit：20 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/affiliate/invitee/detail

Request sample

GET /api/v5/affiliate/invitee/detail?uid=11111111

Request Parameters

Parameter	Type	Required	Description
uid	String	Yes	UID of the invitee. Only applicable to the UID of invitee master account

Returned results

{
    "msg": "",
    "code": "0",
    "data": [
        {
            "accFee": "0",
            "affiliateCode": "HIIIIII",
            "depAmt": "0",
            "firstTradeTime": "",
            "inviteeLevel": "2",
            "inviteeRebateRate": "0.39",
            "joinTime": "1712546713000",
            "kycTime": "",
            "level": "Lv1",
            "region": "Vietnam",
            "totalCommission": "0",
            "volMonth": "0"
        }
    ]
}

Response parameters

Parameter name	Type	Description
inviteeLv	String	Invitee's relative level to the affiliate If the user is a invitee, the level will be `2`.
joinTime	String	Timestamp that the rebate relationship is established, Unix timestamp in millisecond format, e.g. `1597026383085`
inviteeRebateRate	String	Self rebate rate of the invitee (in decimal), e.g. `0.01` represents `10%`
totalCommission	String	Total commission earned from the invitee, unit in `USDT`
firstTradeTime	String	Timestamp that the first trade is completed after the latest rebate relationship is established with the parent affiliate Unix timestamp in millisecond format, e.g. 1597026383085 If user has not traded, "" will be returned
level	String	Invitee trading fee level, e.g. Lv1
depAmt	String	Accumulated amount of deposit in USDT If user has not deposited, 0 will be returned
volMonth	String	Accumulated Trading volume in the current month in USDT If user has not traded, 0 will be returned
accFee	String	Accumulated Amount of trading fee in USDT If there is no any fee, 0 will be returned
kycTime	String	KYC2 verification time. Unix timestamp in millisecond format and the precision is in day If user has not passed KYC2, "" will be returned
region	String	User country or region. e.g. "United Kingdom"
affiliateCode	String	Affiliate invite code that the invitee registered/recalled via

Get the user's affiliate rebate information

This endpoint will be offline soon, please use Get the invitee's detail

It is used to get the user's affiliate rebate information for affiliate.

Rate limit：20 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/users/partner/if-rebate

Request sample

GET /api/v5/users/partner/if-rebate?apiKey=86b02e93-67ab-497d-9970-8cce00a028c3

Request Parameters

Parameter	Type	Required	Description
apiKey	String	Yes	The user's API key. Only applicable to the API key of invitee master account

Returned results

{
    "code": "0",
    "msg": "",
    "data": {
        "result": true,
        "type": "0"
    }
}

Response parameters

Parameter name	Type	Description
result	Boolean	Whether the user is invited by the current affiliate. `true`, `false`
type	String	Whether there is affiliate rebate. `0` There is affiliate rebate `1` There is no affiliate rebate. Because the account which is requesting this endpoint is not affiliate `2` There is no affiliate rebate. Because there is no relationship of invitation or recall, e.g. api key does not exist `4` There is no affiliate rebate. Because the user level is equal to or more than VIP6

Status

GET / Status

Get event status of system upgrade.

Planned system maintenance that may result in short interruption (lasting less than 5 seconds) or websocket disconnection (users can immediately reconnect) will not be announced. The maintenance will only be performed during times of low market volatility.

Rate Limit: 1 request per 5 seconds

HTTP Requests

GET /api/v5/system/status

Request Example

GET /api/v5/system/status

GET /api/v5/system/status?state=canceled

import okx.Status as Status

flag = "0"  # Production trading: 0, Demo trading: 1
statusAPI = Status.StatusAPI(
    domain="https://www.okx.com",
    flag=flag,
)

# Get event status of system upgrade
result = statusAPI.status()
print(result)

Request Parameters

Parameter	Type	Required	Description
state	String	No	System maintenance status `scheduled`: waiting `ongoing`: processing `pre_open`: pre_open `completed`: completed `canceled`: canceled Generally, `pre_open` last about 10 minutes. There will be `pre_open` when the time of upgrade is too long. If this parameter is not filled, the data with status `scheduled`, `ongoing` and `pre_open` will be returned by default

Response Example

{
    "code": "0",
    "data": [
        {
            "begin": "1672823400000",
            "end": "1672823520000",
            "href": "",
            "preOpenBegin": "",
            "scheDesc": "",
            "serviceType": "8",
            "state": "completed",
            "maintType": "1",
            "env": "1",
            "system": "unified",
            "title": "Trading account system upgrade (in batches of accounts)"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
title	String	The title of system maintenance instructions
state	String	System maintenance status
begin	String	Begin time of system maintenance, Unix timestamp format in milliseconds, e.g. `1617788463867`
end	String	Time of resuming trading totally. Unix timestamp format in milliseconds, e.g. `1617788463867`. It is expected end time before `completed`, changed to actual end time after `completed`.
preOpenBegin	String	The time of pre_open. Canceling orders, placing Post Only orders, and transferring funds to trading accounts are back after `preOpenBegin`.
href	String	Hyperlink for system maintenance details, if there is no return value, the default value will be empty. e.g. ""
serviceType	String	Service type `0`: WebSocket `5`: Trading service `6`: Block trading `7`: Trading bot `8`: Trading service (in batches of accounts) `9`: Trading service (in batches of products) `10`: Spread trading `11`: Copy trading `99`: Others (e.g. Suspend partial instruments)
system	String	System `unified`: Trading account
scheDesc	String	Rescheduled description, e.g. `Rescheduled from 2021-01-26T16:30:00.000Z` to `2021-01-28T16:30:00.000Z`
maintType	String	Maintenance type `1`: Scheduled maintenance `2`: Unscheduled maintenance `3`: System disruption
env	String	Environment `1`: Production Trading `2`: Demo Trading

WS / Status channel

Get the status of system maintenance and push when rescheduling and the system maintenance status and end time changes. First subscription: "Push the latest change data"; every time there is a state change, push the changed content.

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "status"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
op	String	Yes	`subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name `status`

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "status"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"statuss\"}]}",
  "connId": "a4d3ae55"
}

Response parameters

Parameter	Type	Required	Description
event	String	Yes	`subscribe` `unsubscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name `status`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "status"
    },
    "data": [
        {
            "begin": "1672823400000",
            "end": "1672825980000",
            "href": "",
            "preOpenBegin": "",
            "scheDesc": "",
            "serviceType": "0",
            "state": "completed",
            "system": "unified",
            "maintType": "1",
            "env": "1",
            "title": "Trading account WebSocket system upgrade",
            "ts": "1672826038470"
        }
    ]
}

Push data parameters

Parameter	Type	Description
arg	Object	Successfully subscribed channel
> channel	String	Channel name
data	Array	Subscribed data
> title	String	The title of system maintenance instructions
> state	String	System maintenance status,`scheduled`: waiting; `ongoing`: processing; `pre_open`: pre_open; `completed`: completed ;`canceled`: canceled. Generally, `pre_open` last about 10 minutes. There will be `pre_open` when the time of upgrade is too long.
> begin	String	Start time of system maintenance, Unix timestamp format in milliseconds, e.g. `1617788463867`
> end	String	Time of resuming trading totally. Unix timestamp format in milliseconds, e.g. `1617788463867`. It is expected end time before `completed`, changed to actual end time after `completed`.
> preOpenBegin	String	The time of pre_open. Canceling orders, placing Post Only orders, and transferring funds to trading accounts are back after `preOpenBegin`.
> href	String	Hyperlink for system maintenance details, if there is no return value, the default value will be empty. e.g. “”
> serviceType	String	Service type, `0`: WebSocket ; `5`: Trading service; `6`: Block trading; `7`: Trading bot; `8`: Trading service (in batches of accounts); `9`: Trading service (in batches of products); `10`: Spread trading; `11`: Copy trading; `99`: Others (e.g. Suspend partial instruments)
> system	String	System, `unified`: Trading account
> scheDesc	String	Rescheduled description, e.g. `Rescheduled from 2021-01-26T16:30:00.000Z to 2021-01-28T16:30:00.000Z`
> maintType	String	Maintenance type `1`: Scheduled maintenance; `2`: Unscheduled maintenance; `3`: System disruption
> env	String	Environment. `1`: Production Trading, `2`: Demo Trading
> ts	String	Push time due to change event, Unix timestamp format in milliseconds, e.g. `1617788463867`

Error Code

Here is the REST API Error Code

REST API

REST API Error Code is from 50000 to 59999.

Public

Error Code from 50000 to 53999

General Class

Error Code	HTTP Status Code	Error Message
0	200
1	200	Operation failed.
2	200	Bulk operation partially succeeded.
50000	400	Body for POST request cannot be empty.
50001	503	Service temporarily unavailable. Try again later
50002	400	JSON syntax error
50004	400	API endpoint request timeout (does not mean that the request was successful or failed, please check the request result).
50005	410	API is offline or unavailable.
50006	400	Invalid Content-Type. Please use "application/JSON".
50007	200	Account blocked.
50008	200	User does not exist.
50009	200	Account is suspended due to ongoing liquidation.
50010	200	User ID cannot be empty.
50011	200	Rate limit reached. Please refer to API documentation and throttle requests accordingly.
50011	429	Too Many Requests
50012	200	Account status invalid. Check account status
50013	429	Systems are busy. Please try again later.
50014	400	Parameter {param0} cannot be empty.
50015	400	Either parameter {param0} or {param1} is required.
50016	400	Parameter {param0} and {param1} is an invalid pair.
50017	200	Position frozen and related operations restricted due to auto-deleveraging (ADL). Try again later
50018	200	{param0} frozen and related operations restricted due to auto-deleveraging (ADL). Try again later
50019	200	Account frozen and related operations restricted due to auto-deleveraging (ADL). Try again later
50020	200	Position frozen and related operations are restricted due to liquidation. Try again later
50021	200	{param0} frozen and related operations are restricted due to liquidation. Try again later
50022	200	Account frozen and related operations are restricted due to liquidation. Try again later
50023	200	Funding fees frozen and related operations are restricted. Try again later
50024	200	Either parameter {param0} or {param1} should be submitted.
50025	200	Parameter {param0} count exceeds the limit {param1}.
50026	500	System error. Try again later
50027	200	This account is restricted from trading. Please contact customer support for assistance.
50028	200	Unable to take the order, please reach out to support center for details.
50029	200	Your account has triggered OKX risk control and is temporarily restricted from conducting transactions. Please check your email registered with OKX for contact from our customer support team.
50030	200	You don't have permission to use this API endpoint
50032	200	Your account has been set to prohibit transactions in this currency. Please confirm and try again
50033	200	Instrument blocked. Please verify trading this instrument is allowed under account settings and try again.
50035	403	This endpoint requires that APIKey must be bound to IP
50036	200	The expTime can't be earlier than the current system time. Please adjust the expTime and try again.
50037	200	Order expired.
50038	200	This feature is unavailable in demo trading
50039	200	Parameter "before" isn't supported for timestamp pagination
50040	200	Too frequent operations, please try again later
50041	200	Your user ID hasn’t been allowlisted. Please contact customer service for assistance.
50044	200	Must select one broker type
50047	200	{param0} has already settled. To check the relevant candlestick data, please use {param1}
50048	200	Switching risk unit may lead position risk increases and be forced liquidated. Please adjust position size, make sure margin is in a safe status.
50049	200	No information on the position tier. The current instrument doesn’t support margin trading.
50050	200	You’ve already activated options trading. Please don’t activate it again.
50051	200	Due to compliance restrictions in your country or region, you cannot use this feature.
50052	200	Due to local laws and regulations, you cannot trade with your chosen crypto.
50053	200	This feature is only available in demo trading.
50055	200	Reset unsuccessful. Assets can only be reset up to 5 times per day.
50056	200	You have pending orders or open positions with this currency. Please reset after canceling all the pending orders/closing all the open positions.
50057	200	Reset unsuccessful. Try again later.
50058	200	This crypto is not supported in an asset reset.
50059	200	Before you continue, you'll need to complete additional steps as required by your local regulators. Please visit the website or app for more details.
50060	200	For security and compliance purposes, please complete the identity verification process to continue using our services.
50061	200	You've reached the maximum order rate limit for this account.
50063	200	You can't activate the credits as they might have expired or are already activated.
50064	200	The borrowing system is unavailable. Try again later.

API Class

Error Code	HTTP Status Code	Error Message
50100	400	API frozen, please contact customer service.
50101	401	APIKey does not match current environment.
50102	401	Timestamp request expired.
50103	401	Request header "OK-ACCESS-KEY" cannot be empty.
50104	401	Request header "OK-ACCESS-PASSPHRASE" cannot be empty.
50105	401	Request header "OK-ACCESS-PASSPHRASE" incorrect.
50106	401	Request header "OK-ACCESS-SIGN" cannot be empty.
50107	401	Request header "OK-ACCESS-TIMESTAMP" cannot be empty.
50108	401	Exchange ID does not exist.
50109	401	Exchange domain does not exist.
50110	401	Your IP {param0} is not included in your API key's IP whitelist.
50111	401	Invalid OK-ACCESS-KEY.
50112	401	Invalid OK-ACCESS-TIMESTAMP.
50113	401	Invalid signature.
50114	401	Invalid authorization.
50115	405	Invalid request method.
50116	200	Fast API is allowed to create only one API key
50118	200	To link the app using your API key, your broker needs to share their IP to be whitelisted
50119	200	API key doesn't exist
50120	200	This API key doesn't have permission to use this function
50120	200	This API key doesn't have permission to use this function
50121	200	You can't access our services through the IP address ({param0})
50122	200	Order amount must exceed minimum amount

Trade Class

Error Code	HTTP Status code	Error Message
51000	400	Parameter {param0} error
51001	200	Instrument ID does not exist
51002	200	Instrument ID does not match underlying index
51003	200	Either client order ID or order ID is required
51004	200	Order failed. For isolated long/short mode of {instId}, the sum of current order size, position quantity in the same direction, and pending orders in the same direction cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current order size: {size} contracts, position quantity in the same direction: {posNumber} contracts, pending orders in the same direction: {pendingNumber} contracts).
51004	200	Order failed. For cross long/short mode of {instId}, the sum of current order size, position quantity in the long and short directions, and pending orders in the long and short directions cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current order size: {size} contracts, position quantity in the long and short directions: {posLongShortNumber} contracts, pending orders in the long and short directions: {pendingLongShortNumber} contracts).
51004	200	Order failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of current order size, current instId position quantity in the long and short directions, current instId pending orders in the long and short directions, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current order size: {size} contracts, current instId position quantity in the long and short directions: {posLongShortNumber} contracts, current instId pending orders in the long and short directions: {pendingLongShortNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51004	200	Order failed. For buy/sell mode of {instId}, the sum of current buy order size, position quantity, and pending buy orders cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current buy order size: {size} contracts, position quantity: {posNumber} contracts, pending buy orders: {pendingNumber} contracts).
51004	200	Order failed. For buy/sell mode of {instId}, the sum of current sell order size, position quantity, and pending sell orders cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current sell order size: {size} contracts, position quantity: {posNumber} contracts, pending sell orders: {pendingNumber} contracts).
51004	200	Order failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of current buy order size, current instId position quantity, current instId pending buy orders, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current buy order size: {size} contracts, current instId position quantity: {posNumber} contracts, current instId pending buy orders: {pendingNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51004	200	Order failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of current sell order size, current instId position quantity, current instId pending sell orders, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, current sell order size: {size} contracts, current instId position quantity: {posNumber} contracts, current instId pending sell orders: {pendingNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51004	200	Order amendment failed. For isolated long/short mode of {instId}, the sum of increment order size by amendment, position quantity in the same direction, and pending orders in the same direction cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amendment: {size} contracts, position quantity in the same direction: {posNumber} contracts, pending orders in the same direction: {pendingNumber} contracts).
51004	200	Order amendment failed. For cross long/short mode of {instId}, the sum of increment order size by amendment, position quantity in the long and short directions, and pending orders in the long and short directions cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amendment: {size} contracts, position quantity in the long and short directions: {posLongShortNumber} contracts, pending orders in the same direction: {pendingLongShortNumber} contracts).
51004	200	Order amendment failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of increment order size by amendment, current instId position quantity in the long and short directions, current instId pending orders in the long and short directions, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amendment: {size} contracts, current instId position quantity in the long and short directions: {posLongShortNumber} contracts, current instId pending orders in the long and short directions: {pendingLongShortNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51004	200	Order amendment failed. For buy/sell mode of {instId}, the sum of increment order size by amending current buy order, position quantity, and pending buy orders cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amending current buy order: {size} contracts, position quantity: {posNumber} contracts, pending buy orders: {pendingNumber} contracts).
51004	200	Order amendment failed. For buy/sell mode of {instId}, the sum of increment order size by amending current sell order, position quantity, and pending sell orders cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amending current sell order: {size} contracts, position quantity: {posNumber} contracts, pending sell orders: {pendingNumber} contracts).
51004	200	Order amendment failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of increment order size by amending current buy order, current instId position quantity, current instId pending buy orders, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amending current buy order: {size} contracts, current instId position quantity: {posNumber} contracts, current instId pending buy orders: {pendingNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51004	200	Order amendment failed. For cross buy/sell mode of {businessType} and instFamily {instFamily}, the sum of increment order size by amending current sell order, current instId position quantity, current instId pending sell orders, and other contracts of the same instFamily cannot be more than {tierLimitQuantity}(contracts) which is the maximum position amount under current leverage. Please lower the leverage or use a new sub-account to place the order again (current leverage: {leverage}×, increment order size by amending current sell order: {size} contracts, current instId position quantity: {posNumber} contracts, current instId pending sell orders: {pendingNumber} contracts, other contracts of the same instFamily: {otherQuote} contracts).
51005	200	Your order amount exceeds the max order amount.
51006	200	Order price is not within the price limit (max buy price: {param0} min sell price: {param1})
51007	200	Order failed. Please place orders of at least 1 contract or more.
51008	200	Order failed. Insufficient {param0} balance in account
51008	200	Order failed. Insufficient {param0} margin in account
51008	200	Order failed. Insufficient {param0} balance in account, and Auto Borrow is not enabled
51008	200	Order failed. Insufficient {param0} margin in account and auto-borrow is not enabled (Portfolio margin mode can try IOC orders to lower the risks)
51008	200	Order failed. The requested borrow amount is larger than the available {param0} borrow amount of your position tier (Existing pending orders and the new order are required to borrow {param1}, Remaining limit {param2}, Limit {param3}, Limit used {param4})
51008	200	Order failed. Exceeds {param0} borrow limit (Limit of master account plus the allocated VIP quota for the current account) (Existing pending orders and the new order are required to borrow {param1}, Remaining limit {param2}, Limit {param3}, Limit used {param4})
51008	200	Order failed. Insufficient {param0} crypto limitation causes insufficient available to borrow
51008	200	Order failed. Insufficient {param0} available in loan pool to borrow.
51008	200	Order failed. Insufficient account balance, and the adjusted equity in `USD` is less than IMR (Portfolio margin mode can try IOC orders to lower the risks)
51008	200	Order failed. The order didn't pass delta verification because if the order were to succeed, the change in adjEq would be smaller than the change in IMR. Increase adjEq or reduce IMR (Portfolio margin mode can try IOC orders to lower the risks)
51009	200	Order blocked. Please contact customer support for assistance.
51010	200	Request unsupported under current account mode
51011	200	Order ID already exists.
51012	200	Token does not exist.
51014	200	Index does not exist.
51015	200	Instrument ID does not match instrument type.
51016	200	Client order ID already exists.
51017	200	Loan amount exceeds borrowing limit.
51018	200	User with option account cannot hold net short positions.
51019	200	No net long positions can be held under cross margin mode in options.
51020	200	Order amount should be greater than the min available amount.
51021	200	The pair or contract is not yet listed
51022	200	Contract suspended.
51023	200	Position does not exist.
51024	200	Trading account is blocked.
51024	200	In accordance with the terms of service, we regret to inform you that we cannot provide services for you. If you have any questions, please contact our customer support.
51024	200	According to your request, this account has been frozen. If you have any questions, please contact our customer support.
51024	200	Your account has recently changed some security settings. To protect the security of your funds, this action is not allowed for now. If you have any questions, please contact our customer support.
51024	200	You have withdrawn all assets in the account. To protect your personal information, the account has been permanently frozen. If you have any questions, please contact our customer support.
51024	200	Your identity could not be verified. To protect the security of your funds, this action is not allowed. Please contact our customer support.
51024	200	Your verified age doesn't meet the requirement. To protect the security of your funds, we cannot proceed with your request. Please contact our customer support.
51024	200	In accordance with the terms of service, trading is currently unavailable in your verified country or region. Close all open positions or contact customer support if you have any questions.
51024	200	In accordance with the terms of service, multiple account is not allowed. To protect the security of your funds, this action is not allowed. Please contact our customer support.
51024	200	Your account is in judicial freezing, and this action is not allowed for now. If you have any questions, please contact our customer support.
51024	200	Based on your previous requests, this action is not allowed for now. If you have any questions, please contact our customer support.
51024	200	Your account has disputed deposit orders. To protect the security of your funds, this action is not allowed for now. Please contact our customer support.
51024	200	Unable to proceed. Please resolve your existing P2P disputes first.
51024	200	Your account might have compliance risk. To protect the security of your funds, this action is not allowed for now. Please contact our customer support.
51024	200	Based on your trading requests, this action is not allowed for now. If you have any questions, please contact our customer support.
51024	200	Your account has triggered risk control. This action is not allowed for now. Please contact our customer support.
51024	200	This account is temporarily unavailable. Please contact our customer support.
51024	200	Withdrawal function of this account is temporarily unavailable. Please contact our customer support.
51024	200	Transfer function of this account is temporarily unavailable. Please contact our customer support.
51024	200	You violated the "Fiat Trading Rules" when you were doing fiat trade, so we'll no longer provide fiat trading-related services for you. The deposit and withdrawal of your account and other trading functions will not be affected.
51024	200	Please kindly check your mailbox and reply to emails from the verification team.
51024	200	According to your request, this account has been closed. If you have any questions, please contact our customer support.
51024	200	Your account might have security risk. To protect the security of your funds, this action is not allowed for now. Please contact our customer support.
51024	200	Your account might have security risk. Convert is now unavailable. Please contact our customer support.
51024	200	Unable to proceed due to account restrictions. We've sent an email to your OKX registered email address regarding this matter, or you can contact customer support via Chat with AI chatbot on our support center page.
51024	200	In accordance with the terms of service, trading is currently unavailable in your verified country or region. Cancel all orders or contact customer support if you have any questions.
51024	200	In accordance with the terms of service, trading is not available in your verified country. If you have any questions, please contact our customer support.
51024	200	This product isn’t available in your country or region due to local laws and regulations. If you don’t reside in this area, you may continue using OKX Exchange products with a valid government-issued ID.
51024	200	Please note that you may not be able to transfer or trade in the first 30 minutes after establishing custody trading sub-accounts. Please kindly wait and try again later.
51024	200	Feature unavailable. Complete Advanced verification to access this feature.
51024	200	You can't trade or deposit now. Update your personal info to restore full account access immediately.
51025	200	Order count exceeds the limit.
51026	200	Instrument type does not match underlying index.
51027	200	Contract expired.
51028	200	Contract under delivery.
51029	200	Contract is being settled.
51030	200	Funding fee is being settled.
51031	200	This order price is not within the closing price range.
51032	200	Closing all positions at market price.
51033	200	The total amount per order for this pair has reached the upper limit.
51034	200	Fill rate exceeds the limit that you've set. Please reset the market maker protection to inactive for new trades.
51035	200	Account does not have permission to submit MM quote order
51036	200	Only Options instrument of the PM account supports MMP orders.
51411	200	Account does not have permission for mass cancellation
51042	200	Under the Portfolio margin account, users can only place MMP orders in cross margin mode in Options.
51043	200	This isolated position doesn't exist.
59509	200	Account does not have permission to reset MMP status
51037	200	This account only supports placing IOC orders to reduce account risk.
51038	200	IOC order already exists under the current risk module.
51039	200	Leverage cannot be adjusted for the cross positions of Expiry Futures and Perpetual Futures under the PM account.
51040	200	Cannot adjust margins for long isolated options positions
51041	200	Portfolio margin account only supports net mode.
51044	200	The order type {param0}, {param1} is not allowed to set stop loss and take profit
51046	200	The take profit trigger price must be higher than the order price
51047	200	The stop loss trigger price must be lower than the order price
51048	200	The take profit trigger price must be lower than the order price
51049	200	The stop loss trigger price must be higher than the order price
51050	200	The take profit trigger price must be higher than the best ask price
51051	200	The stop loss trigger price must be lower than the best ask price
51052	200	The take profit trigger price must be lower than the best bid price
51053	200	The stop loss trigger price must be higher than the best bid price
51054	500	Request timed out. Please try again.
51055	200	Futures Grid is not available in Portfolio Margin mode
51056	200	Action not allowed
51057	200	This bot isn’t available in current account mode. Switch mode in Settings > Account mode to continue.
51058	200	No available position for this algo order
51059	200	Strategy for the current state does not support this operation
51065	200	algoClOrdId already exists.
51068	200	{param0} already exists within algoClOrdId and attachAlgoClOrdId.
51069	200	The option contracts related to current {param0} do not exist
51070	200	You do not meet the requirements for switching to this account mode. Please upgrade the account mode on the OKX website or App
51071	200	You've reached the maximum limit for tag level cancel all after timers.
51072	200	As a spot lead trader, you need to set tdMode to 'spot_isolated' when configured buying lead trade pairs
51073	200	As a spot lead trader, you need to use '/copytrading/close-subposition' for selling assets through lead trades
51074	200	Only the tdMode for lead trade pairs configured by spot lead traders can be set to 'spot_isolated'
51076	200	TP/SL orders in Split TPs only support one-way TP/SL. You can not use slTriggerPx&slOrdPx and tpTriggerPx&tpOrdPx at the same time.
51077	200	You cannot set ‘amendPxOnTriggerTyp’ as 1 for spot and margin trading
51078	200	You are a lead trader. Split TPs are not supported.
51079	200	The number of TP orders with Split TPs attached in a same order cannot exceed {param0}
51080	200	Take-profit trigger price types (tpTriggerPxType) must be the same in an order with Split TPs attached
51081	200	Take-profit trigger prices (tpTriggerPx) cannot be the same in an order with Split TPs attached
51082	200	Take-profit order prices (tpOrdPx) must be market prices in an order with Split TPs attached
51083	200	The total size of TP orders with Split TPs attached in a same order should equal the size of this order
51084	200	The number of SL orders with Split TPs attached in a same order cannot exceed {param0}
51085	200	The number of TP orders cannot be less than 2 when cost-price SL is enabled (amendPxOnTriggerType set as 1) for Split TPs
51086	200	The number of orders with Split TPs attached in a same order cannot exceed {param0}
51538	200	You need to use attachAlgoOrds if you used attachAlgoOrds when placing an order. attachAlgoOrds is not supported if you did not use attachAlgoOrds when placing this order.
51539	200	attachAlgoId or attachAlgoClOrdId cannot be identical when modifying any TP/SL within your split TPs order
51527	200	Order modification failed. At least 1 of the attached TP/SL orders does not exist.
51087	200	Listing canceled for this crypto
51088	200	You can only place 1 TP/SL order to close an entire position
51089	200	The size of the TP order among split TPs attached cannot be empty
51090	200	You can't modify the amount of an SL order placed with a TP limit order.
51091	200	All TP orders in one order must be of the same type.
51092	200	TP order prices (tpOrdPx) in one order must be different.
51093	200	TP limit order prices (tpOrdPx) in one order can't be –1 (market price).
51094	200	You can't place TP limit orders in spot, margin, or options trading.
51095	200	To place TP limit orders at this endpoint, you must place an SL order at the same time.
51096	200	cxlOnClosePos needs to be true to place a TP limit order
51098	200	You can't add a new TP order to an SL order placed with a TP limit order.
51099	200	You can't place TP limit orders as a lead trader.
51178	200	tpTriggerPx&tpOrdPx or slTriggerPx&slOrdPx can't be empty when using attachAlgoClOrdId.
51100	200	Unable to place order. Take profit/Stop loss conditions cannot be added to reduce-only orders.
51101	200	Order failed. The size of the current order cannot be more than {maxSzPerOrder} (contracts).
51102	200	Order failed. The number of pending orders for this instId cannot be more than {maxNumberPerInstrument} (orders).
51103	200	Order failed. The number of pending orders across all instIds under the current {businessType} instFamily cannot be more than {maxNumberPerInstFamily} (orders).
51104	200	Order failed. The aggregated contract quantity for all pending orders across all instIds under the current {businessType} instFamily cannot be more than {maxSzPerInstFamily} (contracts).
51105	200	Order failed. The maximum sum of position quantity and pending orders in the same direction for current instId cannot be more than {maxPositionSzPerInstrument} (contracts).
51106	200	Order failed. The maximum sum of position quantity and pending orders in the same direction across all instIds under the current {businessType} instFamily cannot be more than {maxPostionSzPerInstFamily51106} (contracts).
51107	200	Order failed. The maximum sum of position quantity and pending orders in both directions across all instIds under the current {businessType} instFamily cannot be more than {maxPostionSzPerInstFamily51107} (contracts).
51108	200	Positions exceed the limit for closing out with the market price.
51109	200	No available offer.
51110	200	You can only place a limit order after Call Auction has started.
51111	200	Maximum {param0} orders can be placed in bulk.
51112	200	Close order size exceeds your available size.
51113	429	Market-price liquidation requests too frequent.
51115	200	Cancel all pending close-orders before liquidation.
51116	200	Order price or trigger price exceeds {param0}.
51117	200	Pending close-orders count exceeds limit.
51120	200	Order quantity is less than {param0}. Please try again.
51121	200	Order quantity must be a multiple of the lot size.
51122	200	Order price must be higher than the minimum price {param0}.
51124	200	You can only place limit orders during call auction.
51125	200	Currently there are pending reduce + reverse position orders in margin trading. Please cancel all pending reduce + reverse position orders and continue.
51126	200	Currently there are pending reduce only orders in margin trading. Please cancel all pending reduce only orders and continue.
51127	200	Available balance is 0.
51128	200	Multi-currency margin accounts cannot do cross-margin trading.
51129	200	The value of the position and buy order has reached the position limit. No further buying is allowed.
51130	200	Fixed margin currency error.
51131	200	Insufficient balance.
51132	200	Your position amount is negative and less than the minimum trading amount.
51133	200	Reduce-only feature is unavailable for spot transactions in multi-currency margin accounts.
51134	200	Closing failed. Please check your margin holdings and pending orders. Turn off the Reduce-only to continue.
51135	200	Your closing price has triggered the limit price. The maximum buy price is {param0}.
51136	200	Your closing price has triggered the limit price. The minimum sell price is {param0}.
51137	200	The highest price limit for buy orders is {param0}
51138	200	The lowest price limit for sell orders is {param0}
51139	200	Reduce-only feature is unavailable for the spot transactions by spot mode.
51143	200	Your inquiry failed, please try again later.
51145	200	Placing orders in advance is not supported when margins are self-tranferred in isolated mode.
51147	200	To trade options, make sure you have more than 20,000 USD worth of assets in your trading account first, then activate options trading
51148	200	Failed to place order. The new order may execute an opposite trading direction of your existing reduce-only positions. Cancel or edit pending orders to continue order
51149	500	Order timed out. Please try again.
51150	200	The precision of the number of trades or the price exceeds the limit.
51152	200	Unable to place an order that mixes automatic buy with automatic repayment or manual operation in Quick margin mode.
51155	200	Due to local compliance requirements, trading of this pair or contract is restricted.
51169	200	Failed to place order. You don’t have any positions of this contract. Turn off the Reduce-only to continue.
51170	200	Failed to place order. A reduce-only order can’t be the same trading direction as your existing positions.
51171	200	Failed to edit order. The edited order may execute an opposite trading direction of your existing reduce-only positions. Cancel or edit pending orders to continue.
51174	200	Order failed. The number of {param0} pending orders reached the upper limit of {param1} (orders).
51175	200	Parameters {param0} {param1} and {param2} cannot be empty at the same time
51176	200	Only one parameter can be filled among Parameters {param0} {param1} and {param2}
51177	200	Unavailable to amend {param1} because the price type of the current options order is {param0}
51179	200	Unavailable to place options orders using {param0} in spot mode
51180	200	The range of {param0} should be ({param1}, {param2})
51181	200	ordType must be limit when placing {param0} orders
51182	200	The total number of pending orders under price types pxUsd and pxVol for the current account cannot exceed {param0}.
51185	200	The maximum value allowed per order is {maxOrderValue} USD
51186	200	Order failed. The leverage for {param0} in your current margin mode is {param1}x, which exceeds the platform limit of {param2}x.
51187	200	Order failed. For {param0} {param1} in your current margin mode, the sum of your current order amount, position sizes, and open orders is {param2} contracts, which exceeds the platform limit of {param3} contracts. Reduce your order amount, cancel orders, or close positions.
51201	200	Value of per market order cannot exceed 1,000,000 USDT.
51202	200	Market order amount exceeds the maximum amount.
51203	200	Order amount exceeds the limit {param0}.
51204	200	The price for the limit order cannot be empty.
51205	200	Reduce Only is not available.
51206	200	Please cancel the Reduce Only order before placing the current {param0} order to avoid opening a reverse position.
51220	200	Lead and follow bots only support “Sell” or “Close all positions” when bot stops
51221	200	The profit-sharing ratio must be between 0% and 30%
51222	200	Profit sharing isn’t supported for this type of bot
51223	200	Only lead bot creators can set profit-sharing ratio
51224	200	Profit sharing isn’t supported for this crypto pair
51225	200	Instant trigger isn’t available for follow bots
51226	200	Editing parameters isn’t available for follow bots
51250	200	Algo order price is out of the available range.
51251	200	Bot order type error occurred when placing iceberg order
51252	200	Algo order amount is out of the available range.
51253	200	Average amount exceeds the limit of per iceberg order.
51254	200	Iceberg average amount error occurred.
51255	200	Limit of per iceberg order: Total amount/1000 < x <= Total amount.
51256	200	Iceberg order price variance error.
51257	200	Trailing stop order callback rate error. The callback rate should be {min}< x<={max}%.
51258	200	Trailing stop order placement failed. The trigger price of a sell order must be higher than the last transaction price.
51259	200	Trailing stop order placement failed. The trigger price of a buy order must be lower than the last transaction price.
51260	200	Maximum of {param0} pending trailing stop orders can be held at the same time.
51261	200	Each user can hold up to {param0} pending stop orders at the same time.
51262	200	Maximum {param0} pending iceberg orders can be held at the same time.
51263	200	Maximum {param0} pending time-weighted orders can be held at the same time.
51264	200	Average amount exceeds the limit of per time-weighted order.
51265	200	Time-weighted order limit error.
51267	200	Time-weighted order strategy initiative rate error.
51268	200	Time-weighted order strategy initiative range error.
51269	200	Time-weighted order interval error. Interval must be {%min}<= x<={%max}.
51270	200	The limit of time-weighted order price variance is 0 < x <= 1%.
51271	200	Sweep ratio must be 0 < x <= 100%.
51272	200	Price variance must be 0 < x <= 1%.
51273	200	Total amount must be greater than {param0}.
51274	200	Total quantity of time-weighted order must be larger than single order limit.
51275	200	The amount of single stop-market order cannot exceed the upper limit.
51276	200	Prices cannot be specified for stop market orders.
51277	200	TP trigger price cannot be higher than the last price.
51278	200	SL trigger price cannot be lower than the last price.
51279	200	TP trigger price cannot be lower than the last price.
51280	200	SL trigger price cannot be higher than the last price.
51281	200	Trigger order do not support the tgtCcy parameter.
51282	200	The range of Price variance is {param0}~{param1}
51283	200	The range of Time interval is {param0}~{param1}
51284	200	The range of Average amount is {param0}~{param1}
51285	200	The range of Total amount is {param0}~{param1}
51286	200	The total amount should not be less than {param0}
51287	200	This bot doesn't support current instrument
51288	200	Bot is currently stopping. Do not make multiple attempts to stop.
51289	200	Bot configuration does not exist. Please try again later
51290	200	The Bot engine is being upgraded. Please try again later
51291	200	This Bot does not exist or has been stopped
51292	200	This Bot type does not exist
51293	200	This Bot does not exist
51294	200	This Bot cannot be created temporarily. Please try again later
51295	200	Portfolio margin account does not support ordType {param0} in Trading bot mode
51298	200	Trigger orders are not available in the net mode of Expiry Futures and Perpetual Futures
51299	200	Order did not go through. You can hold a maximum of {param0} orders of this type.
51300	200	TP trigger price cannot be higher than the mark price
51302	200	SL trigger price cannot be lower than the mark price
51303	200	TP trigger price cannot be lower than the mark price
51304	200	SL trigger price cannot be higher than the mark price
51305	200	TP trigger price cannot be higher than the index price
51306	200	SL trigger price cannot be lower than the index price
51307	200	TP trigger price cannot be lower than the index price
51308	200	SL trigger price cannot be higher than the index price
51309	200	Cannot create trading bot during call auction
51310	200	Strategic orders with Iceberg and TWAP order type are not supported when margins are self-transferred in isolated mode.
51311	200	Failed to place trailing stop order. Callback rate should be within {min}<x<={max}
51312	200	Failed to place trailing stop order. Order amount should be within {min}<x<={max}
51313	200	Manual transfer in isolated mode does not support bot trading
51317	200	Trigger orders are not available by margin
51327	200	closeFraction is only available for Expiry Futures and Perpetual Futures
51328	200	closeFraction is only available for reduceOnly orders
51329	200	closeFraction is only available in NET mode
51330	200	closeFraction is only available for stop market orders
51331	200	closeFraction is only available for close position orders
51332	200	closeFraction is not applicable to Portfolio Margin
51333	200	Close position order in hedge-mode or reduce-only order in one-way mode cannot attach TPSL
51340	200	Used margin must be greater than {0}{1}
51341	200	Position closing not allowed
51342	200	Closing order already exists. Please try again later
51343	200	TP price must be less than the lower price
51344	200	SL price must be greater than the upper price
51345	200	Policy type is not grid policy
51346	200	The highest price cannot be lower than the lowest price
51347	200	No profit available
51348	200	Stop loss price must be less than the lower price in the range.
51349	200	Take profit price must be greater than the highest price in the range.
51350	200	No recommended parameters
51351	200	Single income must be greater than 0
51352	200	You can have {0} to {1} trading pairs
51353	200	Trading pair {0} already exists
51354	200	The percentages of all trading pairs should add up to 100%
51355	200	Select a date within {0} - {1}
51356	200	Select a time within {0} - {1}
51357	200	Select a time zone within {0} - {1}
51358	200	The investment amount of each crypto must be greater than {amount}
51359	200	Recurring buy not supported for the selected crypto {0}
51370	200	The range of lever is {0}~{1}
51380	200	Market conditions do not meet the strategy running configuration. You can try again later or adjust your tp/sl configuration.
51381	200	Per grid profit ratio must be larger than 0.1% and less or equal to 10%
51382	200	Stop triggerAction is not supported by the current strategy
51383	200	The min_price is lower than the last price
51384	200	The trigger price must be greater than the min price
51385	200	The take profit price needs to be greater than the min price
51386	200	The min price needs to be greater than 1/2 of the last price
51387	200	Stop loss price must be less than the bottom price
51388	200	This Bot is in running status
51389	200	Trigger price should be lower than {0}
51390	200	Trigger price should be lower than the TP price
51391	200	Trigger price should be higher than the SL price
51392	200	TP price should be higher than the trigger price
51393	200	SL price should be lower than the trigger price
51394	200	Trigger price should be higher than the TP price
51395	200	Trigger price should be lower than the SL price
51396	200	TP price should be lower than the trigger price
51397	200	SL price should be higher than the trigger price
51398	200	Current market meets the stop condition. The bot cannot be created.
51399	200	Max margin under current leverage: {amountLimit} {quoteCurrency}. Enter a smaller amount and try again.
51400	200	Cancellation failed as the order has been filled, canceled or does not exist.
51400	200	Cancellation failed as the order does not exist. (Only applicable to Nitro Spread)
51401	200	Cancellation failed as the order is already canceled. (Only applicable to Nitro Spread)
51402	200	Cancellation failed as the order is already completed. (Only applicable to Nitro Spread)
51403	200	Cancellation failed as the order type does not support cancellation.
51404	200	Order cancellation unavailable during the second phase of call auction.
51405	200	Cancellation failed as you do not have any pending orders.
51406	400	Canceled order count exceeds the limit {param0}.
51407	200	Either order ID or client order ID is required.
51408	200	Pair ID or name does not match the order info.
51409	200	Either pair ID or pair name ID is required.
51410	200	Cancellation failed as the order is already under cancelling status.
51411	200	Account does not have permission for mass cancellation.
51412	200	Cancellation timed out, please try again later.
51412	200	The order has been triggered and can't be canceled.
51413	200	Cancellation failed as the order type is not supported by endpoint.
51415	200	Unable to place order. Spot trading only supports using the last price as trigger price. Please select "Last" and try again.
51500	200	You must enter a price, quantity, or TP/SL
51501	400	Maximum of {param0} orders can be modified.
51502	200	Order failed. Insufficient {param0} balance in account
51502	200	Order failed. Insufficient {param0} margin in account
51502	200	Order failed. Insufficient {param0} balance in account and Auto Borrow is not enabled
51502	200	Order failed. Insufficient {param0} margin in account and Auto Borrow is not enabled (Portfolio margin mode can try IOC orders to lower the risks)
51502	200	Order failed. The requested borrowing amount is larger than the available {param0} borrowing amount of your position tier. Existing pending orders and the new order need to borrow {param1}, remaining quota {param2}, total quota {param3}, used {param4}
51502	200	Order failed. The requested borrowing amount is larger than the available {param0} borrowing amount of your position tier. Existing pending orders and the new order need to borrow {param1}, remaining quota {param2}, total quota {param3}, used {param4}
51502	200	Order failed. The requested borrowing amount is larger than the available {param0} borrowing amount of your main account and the allocated VIP quota. Existing pending orders and the new order need to borrow {param1}, remaining quota {param2}, total quota {param3}, used {param4}
51502	200	Order failed. Insufficient available borrowing amount in {param0} crypto pair
51502	200	Order failed. Insufficient available borrowing amount in {param0} loan pool
51502	200	Order failed. Insufficient account balance and the adjusted equity in USD is smaller than the IMR (Portfolio margin mode can try IOC orders to lower the risks)
51502	200	Order failed. The order didn't pass delta verification. If the order succeeded, the change in adjEq would be smaller than the change in IMR. Increase adjEq or reduce IMR (Portfolio margin mode can try IOC orders to lower the risks)
51503	200	Order modification failed as the order has been filled, canceled or does not exist.
51503	200	Order modification failed as the order does not exist. (Only applicable to Nitro Spread)
51505	200	{instId} is not in call auction
51506	200	Order modification unavailable for the order type.
51508	200	Orders are not allowed to be modified during the call auction.
51509	200	Modification failed as the order has been canceled. (Only applicable to Nitro Spread)
51510	200	Modification failed as the order has been completed. (Only applicable to Nitro Spread)
51511	200	Operation failed as the order price did not meet the requirement for Post Only.
51512	200	Failed to amend orders in batches. You cannot have duplicate orders in the same amend-batch-orders request.
51513	200	Number of modification requests that are currently in progress for an order cannot exceed 3.
51514	200	Order modification failed. The price length must be 32 characters or shorter.
51523	200	Unable to modify the order price of a stop order that closes an entire position. Please modify the trigger price instead.
51524	200	Unable to modify the order quantity of a stop order that closes an entire position. Please modify the trigger price instead.
51525	200	Stop order modification is not available for quick margin
51526	200	Order modification unsuccessful. Take profit/Stop loss conditions cannot be added to or removed from stop orders.
51527	200	Order modification unsuccessful. The stop order does not exist.
51528	200	Unable to modify trigger price type
51529	200	Order modification unsuccessful. Stop order modification only applies to Expiry Futures and Perpetual Futures.
51530	200	Order modification unsuccessful. Take profit/Stop loss conditions cannot be added to or removed from reduce-only orders.
51531	200	Order modification unsuccessful. The stop order must have either take profit or stop loss attached.
51536	200	Unable to modify the size of the options order if the price type is pxUsd or pxVol
51537	200	pxUsd or pxVol are not supported by non-options instruments
51600	200	Status not found.
51601	200	Order status and order ID cannot exist at the same time.
51602	200	Either order status or order ID is required.
51603	200	Order does not exist.
51604	200	Initiate a download request before obtaining the hyperlink
51605	200	You can only download transaction data from the past 2 years
51606	200	Transaction data for the current quarter is not available
51607	200	Your previous download request is still being processed
51608	200	No transaction data found for the current quarter
51610	200	You can't download billing statements for the current quarter.
51611	200	You can't download billing statements for the current quarter.
51620	200	Only affiliates can perform this action
51621	200	The user isn’t your invitee
51156	200	You're leading trades in long/short mode and can't use this API endpoint to close positions
51159	200	You're leading trades in buy/sell mode. If you want to place orders using this API endpoint, the orders must be in the same direction as your existing positions and open orders.
51162	200	You have {instrument} open orders. Cancel these orders and try again
51163	200	You hold {instrument} positions. Close these positions and try again
51165	200	The number of {instrument} reduce-only orders reached the upper limit of {upLimit}. Cancel some orders to proceed.
51166	200	Currently, we don't support leading trades with this instrument
51167	200	Failed. You have block trading open order(s), please proceed after canceling existing order(s).
51168	200	Failed. You have reduce-only type of open order(s), please proceed after canceling existing order(s)
51320	200	The range of coin percentage is {0}%-{1}%
51321	200	You're leading trades. Currently, we don't support leading trades with arbitrage, iceberg, or TWAP bots
51322	200	You're leading trades that have been filled at market price. We've canceled your open stop orders to close your positions
51323	200	You're already leading trades with take profit or stop loss settings. Cancel your existing stop orders to proceed
51324	200	As a lead trader, you hold positions in {instrument}. To close your positions, place orders in the amount that equals the available amount for closing
51325	200	As a lead trader, you must use market price when placing stop orders
51326	200	As a lead trader, you must use market price when placing orders with take profit or stop loss settings
54000	200	Margin trading is not supported.
54001	200	Only Multi-currency margin account can be set to borrow coins automatically.
54004	200	Order placement or modification failed because one of the orders in the batch failed.
54005	200	Switch to isolated margin mode to trade pre-market expiry futures.
54006	200	Pre-market expiry future position limit is {posLimit} contracts.
54007	200	Instrument {instId} is not supported
54008	200	This operation is disabled by the 'mass cancel order' endpoint. Please enable it using this endpoint.
54009	200	The range of {param0} should be [{param1}, {param2}].
54011	200	Pre-market trading contracts are only allowed to reduce the number of positions within 1 hour before delivery. Please modify or cancel the order.

Data class

Error Code	HTTP Status Code	Error Message
52000	200	No market data found.

Spot/Margin

Error Code from 54000 to 54999

Error Code	HTTP Status Code	Error Message
54000	200	Margin trading is not supported.
54001	200	Only Multi-currency margin account can be set to borrow coins automatically.
54004	200	Order placement or modification failed because one of the orders in the batch failed.

Funding

Error Code from 58000 to 58999

Error Code	HTTP Status Code	Error Message
58002	200	Please activate Savings Account first.
58003	200	Savings does not support this currency type
58004	200	Account blocked
58005	200	The {behavior} amount must be equal to or less than {minNum}
58006	200	Service unavailable for token {0}.
58007	200	Assets interface is currently unavailable. Try again later
58008	200	You do not have assets in this currency.
58009	200	Crypto pair doesn't exist
58010	200	Chain {chain} isn't supported
58011	200	Due to local laws and regulations, our services are unavailable to unverified users in {region}. Please verify your account.
58012	200	Due to local laws and regulations, OKX does not support asset transfers to unverified users in {region}. Please make sure your recipient has a verified account.
58013	200	Withdrawals not supported yet, contact customer support for details
58014	200	Deposits not supported yet, contact customer support for details
58015	200	Transfers not supported yet, contact customer support for details
58016	200	The API can only be accessed and used by the trading team's main account
58100	200	The trading product triggers risk control, and the platform has suspended the fund transfer-out function with related users. Please wait patiently.
58101	200	Transfer suspended
58102	429	Rate limit reached. Please refer to API docs and throttle requests accordingly.
58103	200	This account transfer function is temporarily unavailable. Please contact customer service for details.
58104	200	Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please contact customer support to remove the restriction.
58105	200	Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please transfer funds on our website or app to complete identity verification.
58106	200	USD verification failed.
58107	200	Crypto verification failed.
58110	200	Transfers are suspended due to market risk control triggered by your {businessType} {instFamily} trades or positions. Please try again in a few minutes. Contact customer support if further assistance is needed.
58111	200	Fund transfers are unavailable while perpetual contracts are charging funding fees. Try again later.
58112	200	Transfer failed. Contact customer support for assistance
58113	200	Unable to transfer this crypto
58114	400	Transfer amount must be greater than 0
58115	200	Sub-account does not exist.
58116	200	Transfer exceeds the available amount.
58117	200	Transfer failed. Resolve any negative assets before transferring again
58119	200	{0} Sub-account has no permission to transfer out, please set first.
58120	200	Transfers are currently unavailable. Try again later
58121	200	This transfer will result in a high-risk level of your position, which may lead to forced liquidation. You need to re-adjust the transfer amount to make sure the position is at a safe level before proceeding with the transfer.
58122	200	A portion of your spot is being used for Delta offset between positions. If the transfer amount exceeds the available amount, it may affect current spot-derivatives risk offset structure, which will result in an increased Maintenance Margin Requirement (MMR) rate. Please be aware of your risk level.
58123	200	The From parameter cannot be the same as the To parameter.
58124	200	Your transfer is being processed, transfer id:{trId}. Please check the latest state of your transfer from the endpoint (GET /api/v5/asset/transfer-state)
58125	200	Non-tradable assets can only be transferred from sub-accounts to main accounts
58126	200	Non-tradable assets can only be transferred between funding accounts
58127	200	Main account API key does not support current transfer 'type' parameter. Please refer to the API documentation.
58128	200	Sub-account API key does not support current transfer 'type' parameter. Please refer to the API documentation.
58129	200	{param} is incorrect or {param} does not match with 'type'
58131	200	For compliance, we're unable to provide services to unverified users. Verify your identity to make a transfer.
58132	200	For compliance, we're unable to provide services to users with Basic verification (Level 1). Complete Advanced verification (Level 2) to make a transfer.
58200	200	Withdrawal from {0} to {1} is currently not supported for this currency.
58201	200	Withdrawal amount exceeds daily withdrawal limit.
58202	200	The minimum withdrawal amount for NEO is 1, and the amount must be an integer.
58203	200	Please add a withdrawal address.
58204	200	Withdrawal suspended due to your account activity triggering risk control. Please contact customer support for assistance.
58205	200	Withdrawal amount exceeds the upper limit.
58206	200	Withdrawal amount is less than the lower limit.
58207	200	Withdrawal address isn't on the verified address list. (The format for withdrawal addresses with a label is “address:label”.)
58208	200	Withdrawal failed. Please link your email.
58209	200	Sub-accounts don't support withdrawals or deposits. Please use your main account instead
58210	200	Withdrawal fee exceeds the upper limit.
58211	200	Withdrawal fee is lower than the lower limit (withdrawal endpoint: incorrect fee).
58212	200	Withdrawal fee must be {0}% of the withdrawal amount
58213	200	The internal transfer address is illegal. It must be an email, phone number, or account name
58214	200	Withdrawals suspended due to {chainName} maintenance
58215	200	Withdrawal ID does not exist.
58216	200	Operation not allowed.
58217	200	Withdrawals are temporarily suspended for your account due to a risk detected in your withdrawal address. Contact customer support for assistance
58218	200	The internal withdrawal failed. Please check the parameters toAddr and areaCode.
58219	200	You cannot withdraw crypto within 24 hours after changing your mobile number, email address, or Google Authenticator.
58220	200	Withdrawal request already canceled.
58221	200	The toAddr parameter format is incorrect, withdrawal address needs labels. The format should be "address:label".
58222	200	Invalid withdrawal address
58223	200	This is a contract address with higher withdrawal fees
58224	200	This crypto currently doesn't support on-chain withdrawals to OKX addresses. Withdraw through internal transfers instead
58225	200	Asset transfers to unverified users in {region} are not supported due to local laws and regulations.
58226	200	{chainName} is delisted and not available for crypto withdrawal.
58227	200	Withdrawal of non-tradable assets can be withdrawn all at once only
58228	200	Withdrawal of non-tradable assets requires that the API key must be bound to an IP
58229	200	Insufficient funding account balance to pay fees {fee} USDT
58230	200	According to the OKX compliance policy, you will need to complete your identity verification (Level 1) in order to withdraw
58231	200	The recipient has not completed personal info verification (Level 1) and cannot receive your transfer
58232	200	You’ve reached the personal information verification (L1) withdrawal limit, complete photo verification (L2) to increase the withdrawal limit
58233	200	For compliance, we're unable to provide services to unverified users. Verify your identity to withdraw.
58234	200	For compliance, the recipient can't receive your transfer yet. They'll need to verify their identity to receive your transfer.
58235	200	For compliance, we're unable to provide services to users with Basic verification (Level 1). Complete Advanced verification (Level 2) to withdraw.
58236	200	For compliance, a recipient with Basic verification (Level 1) is unable to receive your transfer. They'll need to complete Advanced verification (Level 2) to receive it.
58237	200	According to local laws and regulations, please provide accurate recipient information (rcvrInfo). For the exchange address, please also provide exchange information and recipient identity information ({consientParameters}).
58238	200	Incomplete info. The info of the exchange and the recipient are required if you're withdrawing to an exchange platform.
58240	200	For security and compliance purposes, please complete the identity verification process to use our services. If you prefer not to verify, contact customer support for next steps. We're committed to ensuring a safe platform for users and appreciate your understanding.
58241	200	Due to local compliance requirements, internal withdrawal is unavailable
58242	200	The recipient can't receive your transfer due to their local compliance requirements
58243	200	Your recipient can't receive your transfer as they haven't made a cash deposit yet
58244	200	Make a cash deposit to proceed
58248	200	Due to local regulations, API withdrawal isn't allowed. Withdraw using OKX app or web.
58249	200	API withdrawal for this currency is currently unavailable. Try withdrawing via our app or website.
58300	200	Deposit-address count exceeds the limit.
58301	200	Deposit-address not exist.
58302	200	Deposit-address needs tag.
58303	200	Deposit for chain {chain} is currently unavailable
58304	200	Failed to create invoice.
58305	200	Unable to retrieve deposit address, please complete identity verification and generate deposit address first.
58306	200	According to the OKX compliance policy, you will need to complete your identity verification (Level 1) in order to deposit
58307	200	You've reached the personal information verification (L1) deposit limit, the excess amount has been frozen, complete photo verification (L2) to increase the deposit limit
58308	200	For compliance, we're unable to provide services to unverified users. Verify your identity to deposit.
58309	200	For compliance, we're unable to provide services to users with Basic verification (Level 1). Complete Advanced verification (Level 2) to deposit.
58310	200	Unable to create new deposit address, try again later
58350	200	Insufficient balance.
58351	200	Invoice expired.
58352	200	Invalid invoice.
58353	200	Deposit amount must be within limits.
58354	200	You have reached the daily limit of 10,000 invoices.
58355	200	Permission denied. Please contact your account manager.
58356	200	The accounts of the same node do not support the Lightning network deposit or withdrawal.
58358	200	The fromCcy parameter cannot be the same as the toCcy parameter.
58370	200	You have exceeded the daily limit of small assets conversion.
58373	200	The minimum {ccy} conversion amount is {amount}
58374	200	Small assets should be less than the maximum limit {exchangeOKBLimitMax} {currency}.
58375	200	Small assets should be more than the minimum limit {exchangeOKBLimitMin} {currency}.

Account

Error Code from 59000 to 59999

Error Code	HTTP Status Code	Error Message
59000	200	Settings failed. Close any open positions or orders before modifying settings.
59001	200	Switching unavailable as you have borrowings.
59002	200	Sub-account settings failed. Close any open positions, orders, or trading bots before modifying settings.
59004	200	Only IDs with the same instrument type are supported
59005	200	When margin is manually transferred in isolated mode, the value of the asset intially allocated to the position must be greater than 10,000 USDT.
59006	200	This feature is unavailable and will go offline soon.
59101	200	Leverage can't be modified. Please cancel all pending isolated margin orders before adjusting the leverage.
59102	200	Leverage exceeds the maximum limit. Please lower the leverage.
59103	200	Account margin is insufficient and leverage is too low. Please increase the leverage.
59104	200	The borrowed position has exceeded the maximum position of this leverage. Please lower the leverage.
59105	400	Leverage can't be less than {0}. Please increase the leverage.
59106	200	The max available margin corresponding to your order tier is {0}. Please adjust your margin and place a new order.
59107	200	Leverage can't be modified. Please cancel all pending cross-margin orders before adjusting the leverage.
59108	200	Your account leverage is too low and has insufficient margins. Please increase the leverage.
59109	200	Account equity less than the required margin amount after adjustment. Please adjust the leverage .
59110	200	The instrument type corresponding to this {0} does not support the tgtCcy parameter.
59111	200	Leverage query isn't supported in portfolio margin account mode
59112	200	You have isolated/cross pending orders. Please cancel them before adjusting your leverage
59113	200	According to local laws and regulations, margin trading service is not available in your region. If your citizenship is at a different region, please complete KYC2 verification.
59114	200	According to local laws and regulations, margin trading services are not available in your region
59125	200	{0} does not support the current operation.
59200	200	Insufficient account balance.
59201	200	Negative account balance.
59202	200	No access to max opening amount in cross positions for PM accounts.
59300	200	Margin call failed. Position does not exist.
59301	200	Margin adjustment failed for exceeding the max limit.
59302	200	Margin adjustment failed due to pending close order. Please cancel any pending close orders.
59303	200	Insufficient available margin, add margin or reduce the borrowing amount
59304	200	Insufficient equity for borrowing. Keep enough funds to pay interest for at least one day.
59305	200	Use VIP loan first to set the VIP loan priority
59306	200	Your borrowing amount exceeds the max limit
59307	200	You are not eligible for VIP loans
59308	200	Unable to repay VIP loan due to insufficient borrow limit
59309	200	Unable to repay an amount that exceeds the borrowed amount
59310	200	Your account does not support VIP loan
59311	200	Setup cannot continue. An outstanding VIP loan exists.
59312	200	{currency} does not support VIP loans
59313	200	Unable to repay. You haven't borrowed any ${ccy} (${ccyPair}) in Quick margin mode.
59314	200	The current user is not allowed to return the money because the order is not borrowed
59315	200	viploan is upgrade now. Wait for 10 minutes and try again
59316	200	The current user is not allowed to borrow coins because the currency is in the order in the currency borrowing application.
59317	200	The number of pending orders that are using VIP loan for a single currency cannot be more than {maxNumber} (orders)
59319	200	You can’t repay your loan order because your funds are in use. Make them available for full repayment.
59320	200	Borrow quota exceeded
59321	200	Borrowing isn't available in your region.
59322	200	This action is unavailable for this order.
59323	200	Borrowing amount is less than minimum
59324	200	No available lending offer
59325	200	Loan can only be repaid in full.
59326	200	Invalid lending amount. Lending amount has to be between {minLend} to {lendQuota}.
59327	200	You can’t renew your loan order automatically because the amount you’re renewing isn’t enough to cover your current liability. Repay manually to avoid high overdue interest.
59328	200	Lending APR has to be between {minRate} to {maxRate}.
51152	200	Unable to place an order that mixes automatic buy with automatic repayment or manual operation in Quick margin mode.
59401	200	Holdings already reached the limit.
59402	200	No passed instIDs are in a live state. Please verify instIDs separately.
59500	200	Only the API key of the main account has permission.
59501	200	Each account can create up to 50 API keys
59502	200	This note name already exists. Enter a unique API key note name
59503	200	Each API key can bind up to 20 IP addresses
59504	200	Sub-accounts don't support withdrawals. Please use your main account for withdrawals.
59505	200	The passphrase format is incorrect.
59506	200	API key does not exist.
59507	200	The two accounts involved in a transfer must be 2 different sub-accounts under the same main account.
59508	200	The sub account of {0} is suspended.
59509	200	Account doesn't have permission to reset market maker protection (MMP) status.
59510	200	Sub-account does not exist
59512	200	Unable to set up permissions for ND broker subaccounts. By default, all ND subaccounts can transfer funds out.
59601	200	Subaccount name already exists.
59603	200	Maximum number of subaccounts reached.
59604	200	Only the API key of the main account can access this API.
59606	200	Failed to delete sub-account. Transfer all sub-account funds to your main account before deleting your sub-account.
59608	200	Only Broker accounts have permission to access this API.
59609	200	Broker already exists
59610	200	Broker does not exist
59611	200	Broker unverified
59612	200	Cannot convert time format
59613	200	No escrow relationship established with the subaccount.
59614	200	Managed subaccount does not support this operation.
59615	200	The time interval between the Begin Date and End Date cannot be greater than 180 days.
59616	200	The Begin Date cannot be later than the End Date.
59617	200	Sub-account created. Account level setup failed.
59618	200	Failed to create sub-account.
59619	200	This endpoint does not support ND sub accounts. Please use the dedicated endpoint supported for ND brokers.
59622	200	You're creating a sub-account for a non-existing or incorrect sub-account. Create a sub-account under the ND broker first or use the correct sub-account code.
59623	200	Couldn't delete the sub-account under the ND broker as the sub-account has one or more sub-accounts, which must be deleted first.
59648	200	Your modified spot-in-use amount is insufficient, which may lead to liquidation. Adjust the amount.
59649	200	Disabling spot-derivatives risk offset mode may increase the risk of liquidation. Adjust the size of your positions and ensure your margin-level status is safe.
59650	200	Switching your offset unit may increase the risk of liquidation. Adjust the size of your positions and ensure your margin-level status is safe.
59651	200	Enable spot-derivatives risk offset mode to set your spot-in-use amount.
59652	200	You can only set a spot-in-use amount for crypto that can be used as margin.

WebSocket

Public

Error Code from 60000 to 64002

General Class

Error Code	Error Message
60004	Invalid timestamp
60005	Invalid apiKey
60006	Timestamp request expired
60007	Invalid sign
60008	The current WebSocket endpoint does not support subscribing to {0} channels. Please check the WebSocket URL
60009	Login failure
60011	Please log in
60012	Invalid request
60013	Invalid args
60014	Requests too frequent
60018	Wrong URL or {0} doesn't exist. Please use the correct URL, channel and parameters referring to API document.
60019	Invalid op: {op}
60020	APIKey subscription amount exceeds the limit {0}.
60021	This operation does not support multiple accounts login.
60022	Bulk login partially succeeded
60023	Bulk login requests too frequent
60024	Wrong passphrase
60025	token subscription amount exceeds the limit {0}
60026	Batch login by APIKey and token simultaneously is not supported.
60027	Parameter {0} can not be empty.
60028	The current operation is not supported by this URL. Please use the correct WebSocket URL for the operation.
60029	Only users who are VIP5 and above in trading fee tier are allowed to subscribe to this channel.
60030	Only users who are VIP4 and above in trading fee tier are allowed to subscribe to books50-l2-tbt channel.
60031	The WebSocket endpoint does not allow multiple or repeated logins.
60032	API key doesn't exist.
63999	Login failed due to internal error. Please try again later.
64000	Subscription parameter uly is unavailable anymore, please replace uly with instFamily. More details can refer to: https://www.okx.com/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64001	This channel has been migrated to the '/business' URL. Please subscribe using the new URL. More details can refer to: https://www.okx.com/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64002	This channel is not supported by "/business" URL. Please use "/private" URL(for private channels), or "/public" URL(for public channels). More details can refer to: https://www.okx.com/help-center/changes-to-v5-api-websocket-subscription-parameter-and-url.
64003	Your trading fee tier doesn't meet the requirement to access this channel

Close Frame

Status Code	Reason Text
1009	Request message exceeds the maximum frame length
4001	Login Failed
4002	Invalid Request
4003	APIKey subscription amount exceeds the limit 100
4004	No data received in 30s
4005	Buffer is full, cannot write data
4006	Abnormal disconnection
4007	API key has been updated or deleted. Please reconnect.
4008	The number of subscribed channels exceeds the maximum limit.
4009	The number of subscription channels for this connection exceeds the limit

Overview

API Resources and Support

Tutorials

Python libraries

Customer service

V5 API Key Creation

Generating an API Key

REST Authentication

Making Requests

Signature

WebSocket

Overview

Connect

Connection count limit

Login

Request Parameters

Response parameters

Subscribe

Unsubscribe

Account mode

Production Trading Services

Transaction Timeouts

REST API

WebSocket

Rate Limits

Trading-related APIs

Sub-account rate limit

Fill ratio based sub-account rate limit

Best practices

Trading Account

REST API

Get instruments

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID + InstrumentType

HTTP Request

Request Parameters

Response Parameters

Get balance

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

Request Parameters

Response Parameters

Get bills details (last 7 days)

Rate Limit: 5 requests per second

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

Get bills details (last 3 months)

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

Get account configuration

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

Get maximum order quantity

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

Get maximum available balance/equity

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

Get fee rates

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

Request Parameters

Response Parameters

WebSocket