Overview

Welcome to our API documentation. We provide REST and WebSocket APIs to suit your trading needs.

Please note:

API V5 is only available for upgraded accounts.
For accounts not yet upgraded, please use API V3.
If your account has been upgraded but you still need to use API V3, please refer to API V3 C/W API V5.
Some features are not yet available. As a result, certain unused fields may appear in the response. In this documentation, they are marked with strikethrough for clarity.

API Resources and Support

Tutorials

Learn how to trade with V5 API: Best practice to OKJ’s v5 API

Python libraries

Python SDK will be launched alongside the system specification updated.

Customer service

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-JPY","lever":"5"}

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 30 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":"BTC-JPY"
        }
    ]
}

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` `ANY`
> instId	String	No	Instrument ID

Response Example

{
    "event": "subscribe",
    "arg": {
        "channel": "tickers",
        "instId": "BTC-JPY"
    },
    "connId": "accb8e21"
}

Return parameters

Parameter	Type	Required	Description
event	String	Yes	Event, `subscribe` `error`
arg	Object	No	Subscribed channel
> channel	String	Yes	Channel name
> instType	String	否	产品类型 `SPOT`：币币 `ANY`：全部
~~> instFamily~~	~~String~~	否	~~交易品种~~
> 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": "BTC-JPY"
    }
  ]
}

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` `ANY`
> instId	String	No	Instrument ID

Response Example

{
    "event": "unsubscribe",
    "arg": {
        "channel": "tickers",
        "instId": "BTC-JPY"
    },
    "connId": "d0b44253"
}

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` `ANY`
~~> instFamily~~	~~String~~	No	~~Instrument family~~
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error message

Production Trading Services

The Production Trading URL:
- REST: https://api.okj.com
- Public WebSocket: wss://ws.okj.com:8443/ws/v5/public
- Private WebSocket: wss://ws.okj.com:8443/ws/v5/private - Business WebSocket: wss://ws.okj.com:8443/ws/v5/business

AWS URL:

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

General Info

The rules for placing orders at the exchange level are as follows:

The maximum number of pending orders (including post only orders, limit orders and taker orders that are being processed): 4,000
The maximum number of pending orders per trading symbol is 500, the limit of 500 pending orders applies to the following order types:
- Limit
- Market
- Post only
- Fill or Kill (FOK)
- Immediate or Cancel (IOC)
- Take Profit / Stop Loss (TP/SL)
- Limit and market orders triggered under the order types below:
  - Take Profit / Stop Loss (TP/SL)
The maximum number of pending algo orders:
- TP/SL order: 100 per instrument

The rules for the returning data are as follows:

code and msg represent the request result or error reason when the return data has code, and has not sCode;
It is sCode and sMsg that represent the request result or error reason when the return data has sCode rather than code and msg.

Transaction Timeouts

Orders may not be processed in time due to network delay or busy OKJ 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://api.okj.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-JPY",
  "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-JPY",
        "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
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.

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"


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

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

Request Parameters

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

Response Example

{
    "code": "0",
    "data": [
        {
            "auctionEndTime": "",
            "baseCcy": "BTC",
            "expTime": "",
            "instId": "BTC-JPY",
            "instType": "SPOT",
            "listTime": "1704876947000",
            "lotSz": "0.00000001",
            "maxLmtAmt": "1000000",
            "maxLmtSz": "9999999999",
            "maxMktAmt": "1000000",
            "maxMktSz": "1000000",
            "maxStopSz": "1000000",
            "minSz": "0.00001",
            "quoteCcy": "JPY",
            "state": "live",
            "ruleType": "normal",
            "tickSz": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID, e.g. `BTC-JPY`
baseCcy	String	Base currency, e.g. `BTC` in`BTC-JPY` Only applicable to `SPOT`
quoteCcy	String	Quote currency, e.g. `JPY` in `BTC-JPY` Only applicable to `SPOT`
listTime	String	Listing time, Unix timestamp format in milliseconds, e.g. `1597026383085`
auctionEndTime	String	The end time of call auction, Unix timestamp format in milliseconds, e.g. `1597026383085` Only applicable to `SPOT` that are listed through call auctions, return "" in other cases
expTime	String	Expiry time Applicable to `SPOT`. It is the instrument offline time when there is `SPOT` manual offline. Update once change.
tickSz	String	Tick size, e.g. `0.0001`
lotSz	String	Lot size If it is `SPOT`, the value is the quantity in `base currency`.
minSz	String	Minimum order size If it is `SPOT`, the value is the quantity in `base currency`.
state	String	Instrument status `live` `suspend` `preopen`: certain symbols before they go 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 `SPOT`, the value is the quantity in `base currency`.
maxMktSz	String	The maximum order quantity of a single market order. If it is `SPOT`, the value is the quantity in `JPY`.
maxLmtAmt	String	Max JPY amount for a single limit order
maxMktAmt	String	Max JPY amount for a single market order Only applicable to `SPOT`
maxStopSz	String	The maximum order quantity of a single stop market order. If it is `SPOT`, the value is the quantity in `JPY`.
~~uly~~	~~String~~	~~Underlying, e.g. `BTC-JPY`~~
~~instFamily~~	~~String~~	~~Instrument family, e.g. `BTC-JPY`~~
~~settleCcy~~	~~String~~	~~Settlement and margin currency, e.g. `BTC`~~
~~ctVal~~	~~String~~	~~Contract value~~
~~ctMult~~	~~String~~	~~Contract multiplier~~
~~ctValCcy~~	~~String~~	~~Contract value currency~~
~~optType~~	~~String~~	~~Option type, `C`: Call, `P`: Put~~
~~stk~~	~~String~~	~~Strike price~~
~~lever~~	~~String~~	~~Max Leverage, Not applicable to `SPOT`~~
~~ctType~~	~~String~~	~~Contract type~~
~~maxTwapSz~~	~~String~~	~~The maximum order quantity of a single TWAP order. If it is `SPOT, 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`, 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`, the value is the quantity in `base currency`.~~

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"

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

# 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": [
        {
            "details": [
                {
                    "availBal": "4834.317093622894",
                    "cashBal": "4850.435693622894",
                    "ccy": "JPY",
                    "eq": "4992.890093622894",
                    "eqJpy": "4991.542013297616",
                    "frozenBal": "158.573",
                    "ordFrozen": "0",
                    "stgyEq": "150",
                    "uTime": "1705449605015",
                    "spotBal": "",
                    "openAvgPx": "",
                    "accAvgPx": "",
                    "spotUpl": "",
                    "spotUplRatio": "",
                    "totalPnl": "",
                    "totalPnlRatio": ""
                }
            ],
            "totalEq": "55837.43556134779",
            "uTime": "1705474164160"
        }
    ],
    "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 `JPY`
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`
> availBal	String	Available balance of currency
> frozenBal	String	Frozen balance of currency
> ordFrozen	String	Margin frozen for open orders Applicable to `Spot mode`
> eqJpy	String	Equity in `JPY` of currency
> stgyEq	String	Strategy equity
> spotBal	String	Spot balance. The unit is currency, e.g. BTC. Clicking knows more
> openAvgPx	Array	Spot average cost price. The unit is JPY. Clicking knows more
> accAvgPx	Array	Spot accumulated cost price. The unit is JPY. Clicking knows more
> spotUpl	String	Spot unrealized profit and loss. The unit is JPY. Clicking knows more
> spotUplRatio	String	Spot unrealized profit and loss ratio. Clicking knows more
> totalPnl	String	Spot accumulated profit and loss. The unit is JPY. Clicking knows more
> totalPnlRatio	String	Spot accumulated profit and loss ratio. Clicking knows more
~~isoEq~~	~~String~~	~~Isolated margin equity in `JPY`~~
~~adjEq~~	~~String~~	~~Adjusted / Effective equity in `JPY`~~
~~ordFroz~~	~~String~~	~~Cross margin frozen for pending orders in `JPY`~~
~~imr~~	~~String~~	~~Initial margin requirement in `JPY`~~
~~mmr~~	~~String~~	~~Maintenance margin requirement in `JPY`~~
~~borrowFroz~~	~~String~~	~~Potential borrowing IMR of the account in `JPY`~~
~~mgnRatio~~	~~String~~	~~Margin ratio in `JPY`~~
~~notionalJpy~~	~~String~~	~~Notional value of positions in `JPY`~~
~~upl~~	~~String~~	~~Cross-margin info of unrealized profit and loss at the account level in `JPY`~~
~~> isoEq~~	~~String~~	~~Isolated margin equity of currency~~
~~> availEq~~	~~String~~	~~Available equity of currency~~
~~> disEq~~	~~String~~	~~Discount equity of currency in `JPY`.~~
~~> fixedBal~~	~~String~~	~~Frozen balance~~
~~> liab~~	~~String~~	Liabilities of currency It is a positive value, e.g. `21625.64`
~~> upl~~	~~String~~	~~The sum of the unrealized profit & loss of all margin and derivatives positions of currency.~~
~~> uplLiab~~	~~String~~	~~Liabilities due to Unrealized loss of currency~~
~~> crossLiab~~	~~String~~	~~Cross liabilities of currency~~
~~> isoLiab~~	~~String~~	~~Isolated liabilities of currency~~
~~> 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.
~~> imr~~	~~String~~	~~Cross initial margin requirement at the currency level~~
~~> mmr~~	~~String~~	~~Cross maintenance margin requirement at the currency level~~
~~> interest~~	~~String~~	Accrued interest of currency It is a positive value, e.g. `9.01`
~~> 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.
~~> maxLoan~~	~~String~~	~~Max loan of currency~~
~~> borrowFroz~~	~~String~~	~~Potential borrowing IMR of currency in `JPY`~~
~~> notionalLever~~	~~String~~	~~Leverage of currency~~
~~> isoUpl~~	~~String~~	~~Isolated unrealized profit and loss of currency~~
~~> spotInUseAmt~~	~~String~~	Spot in use amount
~~> clSpotInUseAmt~~	~~String~~	~~User-defined spot risk offset amount~~
~~> maxSpotInUse~~	~~String~~	~~Max possible spot risk offset amount~~
~~> spotIsoBal~~	~~String~~	Spot isolated balance Applicable to copy trading
~~> smtSyncEq~~	~~String~~	Smark sync equity The default is "0", only applicable to copy trader
~~> spotCopyTradingEq~~	~~String~~	Spot smart sync equity. The default is "0", only applicable to copy trader.

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"


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

# 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`
instId	String	No	Instrument ID, e.g. `BTC-JPY`
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 `ts`. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp `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": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "JPY",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-JPY",
        "instType": "SPOT",
        "mgnMode": "cash",
        "notes": "",
        "ordId": "623950854525124608",
        "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
bal	String	Balance at the account level
sz	String	Quantity
px	String	Price which related to subType Trade filled price for `1`: Buy `2`: Sell
ccy	String	Account balance currency
fee	String	Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. Trading fee rule
mgnMode	String	Margin mode `cash` When bills are not generated by position changes, the field returns ""
instId	String	Instrument ID, e.g. `BTC-JPY`
ordId	String	Order ID Return order ID when the type is `2`/`5`/`9` Return "" when there is no order.
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
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.
~~posBalChg~~	~~String~~	~~Change in balance amount at the position level~~
~~posBal~~	~~String~~	~~Balance at the position level~~
~~pnl~~	~~String~~	~~Profit and loss~~
~~interest~~	~~String~~	~~Interest~~
~~fillIdxPx~~	~~String~~	~~Index price at the moment of trade execution~~
~~fillMarkPx~~	~~String~~	~~Mark price~~
~~fillPxVol~~	~~String~~	~~Implied volatility~~
~~fillPxUsd~~	~~String~~	~~Options price~~
~~fillMarkVol~~	~~String~~	~~Mark volatility~~
~~fillFwdPx~~	~~String~~	~~Forward price~~

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"


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

# 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`
instId	String	No	Instrument ID, e.g. `BTC-JPY`
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 `ts`. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp `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": [{
        "bal": "8694.2179403378290202",
        "balChg": "0.0219338232210000",
        "billId": "623950854533513219",
        "ccy": "JPY",
        "clOrdId": "",
        "execType": "T",
        "fee": "-0.000021955779",
        "fillTime": "1695033476166",
        "from": "",
        "instId": "BTC-JPY",
        "instType": "SPOT",
        "mgnMode": "cash",
        "notes": "",
        "ordId": "623950854525124608",
        "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
bal	String	Balance at the account level
sz	String	Quantity
px	String	Price which related to subType Trade filled price for `1`: Buy `2`: Sell
ccy	String	Account balance currency
fee	String	Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. Trading fee rule
mgnMode	String	Margin mode `cash` When bills are not generated by position changes, the field returns ""
instId	String	Instrument ID, e.g. `BTC-JPY`
ordId	String	Order ID Return order ID when the type is `2`/`5`/`9` Return "" when there is no order.
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
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.
~~posBalChg~~	~~String~~	~~Change in balance amount at the position level~~
~~posBal~~	~~String~~	~~Balance at the position level~~
~~pnl~~	~~String~~	~~Profit and loss~~
~~interest~~	~~String~~	~~Interest~~
~~fillIdxPx~~	~~String~~	~~Index price at the moment of trade execution~~
~~fillMarkPx~~	~~String~~	~~Mark price~~
~~fillPxVol~~	~~String~~	~~Implied volatility~~
~~fillPxUsd~~	~~String~~	~~Options price~~
~~fillMarkVol~~	~~String~~	~~Mark volatility~~
~~fillFwdPx~~	~~String~~	~~Forward price~~

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"


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

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

Request Parameters

none

Response Example

{
    "code": "0",
    "data": [
        {
            "acctLv": "1",
            "acctStpMode": "cancel_maker",
            "ip": "",
            "kycLv": "",
            "label": "v5 test",
            "level": "Lv1",
            "levelTmp": "",
            "mainUid": "44705892343619584",
            "perm": "read_only,withdraw,trade",
            "roleType": "0",
            "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
acctStpMode	String	Account self-trade protection mode `cancel_maker`: cancels the maker order
level	String	The user level of the current real trading volume on the platform, e.g `Lv1`
roleType	String	Role type `0`: General user
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
~~posMode~~	~~String~~	Position mode `long_short_mode`: long/short
~~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
~~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
~~spotOffsetType~~	~~String~~	~~Risk offset type~~
~~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~~
~~liquidationGear~~	~~String~~	~~The margin ratio level of liquidation 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
~~type~~	~~String~~	Account type `0`: Main account `1`: Standard sub-account `2`: Managed trading sub-account `5`: Custody trading sub-account - Copper `9`: Managed trading sub-account - Copper `12`: Custody trading sub-account - Komainu

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-JPY&tdMode=cash

import okx.Account as Account

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


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

# Get maximum buy/sell amount or open amount
result = accountAPI.get_max_order_size(
    instId="BTC-JPY",
    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-JPY,ETH-JPY`
tdMode	String	Yes	Trade mode `cash`

Response Example

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

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
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
~~ccy~~	~~String~~	~~Currency used for margin~~

Get maximum available balance/equity

Available balance .

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-JPY
GET /api/v5/account/max-avail-size?instId=BTC-JPY&tdMode=cash

import okx.Account as Account

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


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

# Get maximum available transaction amount for SPOT BTC-JPY
result = accountAPI.get_max_avail_size(
    instId="BTC-JPY",
    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-JPY,ETH-JPY`
tdMode	String	Yes	Trade mode `cash`

Response Example

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

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
availBuy	String	Maximum available balance/equity to buy
availSell	String	Maximum available balance/equity 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-JPY
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-JPY

import okx.Account as Account

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


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

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

Request Parameters

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

Response Example

{
  "code": "0",
  "msg": "",
  "data": [{
    "instType": "SPOT",
    "level": "lv1",
    "maker": "-0.0008",
    "taker": "-0.001",
    "ruleType": "normal",
    "ts": "1608623351857"
  }
  ]
}

Response Parameters

Parameter	Type	Description
level	String	Fee rate Level
taker	String	For `SPOT`, it is taker fee rate of the JPY trading pairs.
maker	String	For `SPOT`, it is maker fee rate of the JPY trading pairs.
instType	String	Instrument type
ruleType	String	Trading rule types `normal`: normal trading `pre_market`: pre-market trading
ts	String	Data return time, Unix timestamp format in milliseconds, e.g. `1597026383085`
~~delivery~~	~~String~~	~~Delivery fee rate~~
~~exercise~~	~~String~~	~~Fee rate for exercising the option~~
~~category~~	~~String~~	~~Currency category. Note: this parameter is already deprecated~~

Get all fee rates

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/trade-fee-all

Request Example

# Query all trade fee rate of SPOT
GET /api/v5/account/trade-fee-all?instType=SPOT

import okx.Account as Account

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


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

# Get trading fee rates of current account
result = accountAPI.get_fee_rates_all(
    instType="SPOT"
)
print(result)

Request Parameters

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

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
                 "instId":"BTC-JPY",
                 "instType":"SPOT",
                 "level":"LV1",
                 "maker":"0.0001",
                 "ruleType":"normal",
                 "taker":"-0.0001",
                 "ts":"1746766729131"
                 },
                 {
                 "instId":"ETH-JPY",
                 "instType":"SPOT",
                 "level":"LV1",
                 "maker":"0.0001",
                 "ruleType":"normal",
                 "taker":"-0.0001",
                 "ts":"1746766729131"
                 }
    ]
}

Response Parameters

Parameter	Type	Description
level	String	Fee rate Level
taker	String	For `SPOT`, it is taker fee rate of the JPY trading pairs.
maker	String	For `SPOT`, it is maker fee rate of the JPY trading pairs.
instType	String	Instrument type
ruleType	String	Trading rule types `normal`: normal trading `pre_market`: pre-market trading
ts	String	Data return time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get maximum withdrawals

Retrieve the maximum transferable amount from trading account to funding account. 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/max-withdrawal

Request Example

GET /api/v5/account/max-withdrawal

import okx.Account as Account

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


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

# Get maximum withdrawals
result = accountAPI.get_max_withdrawal()
print(result)

Request Parameters

Parameter	Type	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": [{
            "ccy": "BTC",
            "maxWd": "124"
        },
        {
            "ccy": "ETH",
            "maxWd": "10"
        }
    ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
maxWd	String	Max withdrawal
~~maxWdEx~~	~~String~~	~~Max withdrawal~~
~~spotOffsetMaxWd~~	~~String~~	~~Max withdrawal under Spot-Derivatives risk offset mode~~
~~spotOffsetMaxWdEx~~	~~String~~	~~Max withdrawal under Spot-Derivatives risk offset mode~~

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": [{
        "details": [{
            "accAvgPx":"13726482.110594058",
            "availBal":"4.02776655",
            "cashBal":"4.02776655",
            "ccy":"BTC",
            "eq":"4.02776655",
            "eqJpy":"58437022.59366886",
            "frozenBal":"0",
            "openAvgPx":"13726482.110594058",
            "ordFrozen":"0",
            "spotBal":"1.0099999999999998",
            "spotUpl":"789881.0993500013",
            "spotUplRatio":"0.0569745757219434",
            "stgyEq":"0",
            "totalPnl":"789881.0993499998",
            "totalPnlRatio":"0.0569745757219432",
            "uTime":"1732523313429"
        }],
        "totalEq": "55868.06403501676",
        "uTime": "1705564223311"
    }]
}

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 `JPY`
> 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`
>> availBal	String	Available balance of currency
>> frozenBal	String	Frozen balance of currency
>> ordFrozen	String	Margin frozen for open orders
>> eqJpy	String	Equity `JPY` of currency
>> stgyEq	String	Strategy equity
>> spotBal	String	Spot balance. The unit is currency, e.g. BTC.
>> openAvgPx	Array	Spot average cost price. The unit is JPY.
>> accAvgPx	Array	Spot accumulated cost price. The unit is JPY.
>> spotUpl	String	Spot unrealized profit and loss. The unit is JPY.
>> spotUplRatio	String	Spot unrealized profit and loss ratio.
>> totalPnl	String	Spot accumulated profit and loss. The unit is JPY.
>> totalPnlRatio	String	Spot accumulated profit and loss ratio.

Balance and position channel

Retrieve account balance and position information. Data will be pushed when triggered by events such as filled order, funding transfer.
This channel applies to getting the account cash balance and the change of position asset ASAP.
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

{
    "op": "subscribe",
    "args": [{
        "channel": "balance_and_position"
    }]
}

Request Parameters

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

Response Example

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

Failure Response Example

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

Response parameters

Parameter	Type	Required	Description
event	String	Yes	Operation `subscribe` `unsubscribe` `error`
arg	Object	No	List of subscribed channels
> channel	String	Yes	Channel name `balance_and_position`
code	String	No	Error code
msg	String	No	Error message
connId	String	Yes	WebSocket connection ID

Push Data Example

{
    "arg": {
        "channel": "balance_and_position",
        "uid": "77982378738415879"
    },
    "data": [{
        "pTime": "1597026383085",
        "eventType": "snapshot",
        "balData": [{
            "ccy": "BTC",
            "cashBal": "1",
            "uTime": "1597026383085"
        }],
        "trades": [{
            "instId": "BTC-JPY",
            "tradeId": "2",
        }]
    }]
}

Push data parameters

Parameter	Type	Description
arg	Object	Channel to subscribe to
> channel	String	Channel name
> uid	String	User Identifier
data	Array	Subscribed data
> pTime	String	Push time of both balance and position information, millisecond format of Unix timestamp, e.g. `1597026383085`
> eventType	String	Event Type `snapshot`,`transferred`,`filled`
> balData	String	Balance data
>> ccy	String	Currency
>> cashBal	String	Cash Balance
>> uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> trades	Array	Details of trade
>> instId	String	Instrument ID, e.g. `BTC-JPY`
>> tradeId	String	Trade ID

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

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/order

Request Example

 place order for SPOT
 POST /api/v5/trade/order
 body
 {
    "instId":"BTC-JPY",
    "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"


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

# Spot mode, limit order
result = tradeAPI.place_order(
    instId="BTC-JPY",
    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-JPY`
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. Only applicable to general order. It will not be posted to algoId when placing TP/SL order after the general order is filled completely.
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. 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
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 For condition TP order, if you fill in this parameter, you should fill in the take-profit order price as well.
> tpOrdPx	String	Conditional	Take-profit order price For condition TP order, if you fill in this parameter, you should fill in the take-profit trigger price as well. For limit TP order, you need to fill in this parameter, take-profit trigger needn‘t to be filled.
> 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
> 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

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "312269865356374016",
      "tag": "",
      "ts":"1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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 will be filled with market price (by swiping opposite order book). As the filled price for market orders cannot be determined in advance, OKJ 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.

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-JPY market price is 200, and the locked balance of the user is 3,000 JPY, as 200*10 < 3,000, the market order of 10 LTC is fully executed; If the market is too volatile and the LTC-JPY 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 JPY 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 JPY as an example, and the user can sell 1,200 JPY, 1,000 < 1,200, the order is accepted. When the LTC-JPY 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 JPY is fully executed; If the market is too volatile and the LTC-JPY 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 JPY.

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-JPY",
        "tdMode":"cash",
        "clOrdId":"b15",
        "side":"buy",
        "ordType":"limit",
        "px":"2.15",
        "sz":"2"
    },
    {
        "instId":"BTC-JPY",
        "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"


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

# Place multiple orders 
place_orders_without_clOrdId = [
    {"instId": "BTC-JPY", "tdMode": "cash", "clOrdId": "b15", "side": "buy", "ordType": "limit", "px": "2.15", "sz": "2"},
    {"instId": "BTC-JPY", "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-JPY`
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	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. 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
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 For condition TP order, if you fill in this parameter, you should fill in the take-profit order price as well.
> tpOrdPx	String	Conditional	Take-profit order price For condition TP order, if you fill in this parameter, you should fill in the take-profit trigger price as well. For limit TP order, you need to fill in this parameter, take-profit trigger needn't to be filled.
> 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.
> 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":"",
            "ts":"1695190491421",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "tag":"",
            "ts":"1695190491421",
            "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY"
}

import okx.Trade as Trade

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


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

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

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-JPY`
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",
            "ts":"1695190491421",
            "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY",
        "ordId":"590908157585625111"
    },
    {
        "instId":"BTC-JPY",
        "ordId":"590908544950571222"
    }
]

import okx.Trade as Trade

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


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

# Cancel multiple orders by ordId
cancel_orders_with_orderId = [
    {"instId": "BTC-JPY", "ordId": "590908157585625111"},
    {"instId": "BTC-JPY", "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-JPY`
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",
            "ts":"1695190491421",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "ts":"1695190491421",
            "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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 of lead instruments for Copy Trading: 4 requests 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-order

Request Example

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

import okx.Trade as Trade

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


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

# Amend order
result = tradeAPI.amend_order(
    instId="BTC-JPY",
    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 and it has to be larger than 0. 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.
> newTpOrdPx	String	Conditional	Take-profit order 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
> newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price If you want to add the take-profit, this parameter is required
> newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last price 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",
         "ts":"1695190491421",
         "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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

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-JPY"
    },
    {
        "ordId":"590909308792049555",
        "newSz":"2",
        "instId":"BTC-JPY"
    }
]

import okx.Trade as Trade

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

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

# Amend incomplete orders in batches by ordId
amend_orders_with_orderId = [
    {"instId": "BTC-JPY", "ordId": "590909308792049444","newSz":"2"},
    {"instId": "BTC-JPY", "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 and it has to be larger than 0. 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.
> newTpOrdPx	String	Conditional	Take-profit order 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
> newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price If you want to add the take-profit, this parameter is required
> newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last price 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",
            "ts":"1695190491421",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "ts":"1695190491421",
            "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY

import okx.Trade as Trade

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

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

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

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-JPY` 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-JPY",
            "instType": "SPOT",
            "isTpLimit": "false",            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",            "px": "",            "rebate": "0",
            "rebateCcy": "JPY",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",            "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
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
tdMode	String	Trade mode
accFillSz	String	Accumulated fill quantity The unit is `base_ccy` for SPOT, e.g. BTC-JPY, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`;
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 , e.g. BTC-JPY, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`;
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`
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
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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.
> tpOrdKind	String	TP order kind `condition` `limit`
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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
> failCode	String	The error code when failing to place TP/SL order, e.g. 51020 The default is ""
> failReason	String	The error reason when failing to place TP/SL order. The default is ""
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, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
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, 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`
isTpLimit	String	Whether it is TP limit order. 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`
~~ccy~~	~~String~~	~~Margin currency~~
~~pxJpy~~	~~String~~	~~Options price~~
~~pxVol~~	~~String~~	~~Implied volatility of the options orderOnly applicable to options;~~
~~pxType~~	~~String~~	~~Price type of options~~
~~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`.~~
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size~~
~~quickMgnType~~	~~String~~	~~Quick Margin type, Only applicable to Quick Margin Mode of isolated margin~~

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"


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

# 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-JPY`
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-JPY",
            "instType": "SPOT",
            "isTpLimit": "false",            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "1752588852617379840",
            "ordType": "post_only",
            "pnl": "0",            "px": "13013.5",            "rebate": "0",
            "rebateCcy": "JPY",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "live",            "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
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)
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
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`
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
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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.
> tpOrdKind	String	TP order kind `condition` `limit`
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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
> failCode	String	The error code when failing to place TP/SL order, e.g. 51020 The default is ""
> failReason	String	The error reason when failing to place TP/SL order. The default is ""
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 , it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
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`
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 "".
isTpLimit	String	Whether it is TP limit order. true or false
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.
~~ccy~~	~~String~~	~~Margin currency~~
~~pxJpy~~	~~String~~	~~Options price~~
~~pxVol~~	~~String~~	~~Implied volatility of the options orderOnly applicable to options~~
~~pxType~~	~~String~~	~~Price type of options~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size.~~
~~quickMgnType~~	~~String~~	~~Quick Margin type~~

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"


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

# 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-JPY`
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`
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 `cTime`. Unix timestamp format in milliseconds, e.g. 1597026383085
end	String	No	Filter with an end timestamp `cTime`. 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-JPY",
            "instType": "SPOT",            "linkedAlgoOrd": {
                "algoId": ""
            },
            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",            "px": "",            "rebate": "0",
            "rebateCcy": "JPY",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362",
            "isTpLimit": "false"
        }
    ],
    "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
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
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`
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
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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.
> tpOrdKind	String	TP order kind `condition` `limit`
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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
> failCode	String	The error code when failing to place TP/SL order, e.g. 51020 The default is ""
> failReason	String	The error reason when failing to place TP/SL order. The default is ""
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 , it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
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 , 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`
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 "".
isTpLimit	String	Whether it is TP limit order. true or false
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
~~ccy~~	~~String~~	~~Margin currency~~
~~pxJpy~~	~~String~~	~~Options price~~
~~pxVol~~	~~String~~	~~Implied volatility of the options orderOnly applicable to options;~~
~~pxType~~	~~String~~	~~Price type of options~~
~~posSide~~	~~String~~	~~Position side~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size. Valid options: true or false.~~

GET / Order history (last 3 months)

Get completed orders which are placed in the last 3 months, including those placed 3 months ago but completed in the last 3 months.

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

import okx.Trade as Trade

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


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

# Get completed SPOT orders which are placed in the last 3 months
result = tradeAPI.get_orders_history_archive(
    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-JPY`
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`
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 `cTime`. Unix timestamp format in milliseconds, e.g. 1597026383085
end	String	No	Filter with an end timestamp `cTime`. 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-JPY",
            "instType": "SPOT",            "ordId": "680800019749904384",
            "ordType": "market",
            "pnl": "0",            "px": "",            "rebate": "0",
            "rebateCcy": "JPY",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "source": "",
            "state": "filled",            "sz": "100",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "quote_ccy",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "tradeId": "744876980",
            "uTime": "1708587373362",
            "isTpLimit": "false",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ],
    "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
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)
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
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`
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
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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.
> tpOrdKind	String	TP order kind `condition` `limit`
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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
> failCode	String	The error code when failing to place TP/SL order, e.g. 51020 The default is ""
> failReason	String	The error reason when failing to place TP/SL order. The default is ""
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 , it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
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`
rebateCcy	String	Rebate currency
rebate	String	Rebate amount, only applicable to spot , 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`
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 "".
isTpLimit	String	Whether it is TP limit order. true or false
uTime	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
~~ccy~~	~~String~~	~~Margin currency~~
~~pxJpy~~	~~String~~	~~Options price~~
~~pxVol~~	~~String~~	~~Implied volatility of the options orderOnly applicable to options;~~
~~pxType~~	~~String~~	~~Price type of options~~
~~posSide~~	~~String~~	~~Position side~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size. Valid options: true or false.~~

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"


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

# 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-JPY`
ordId	String	No	Order ID
subType	String	No	Transaction type `1`: Buy `2`: Sell
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 `ts`. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp `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",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",            "fee": "-0.00000192834",            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",            "instId": "BTC-JPY",
            "clOrdId": "",            "billId": "680800019754098688",
            "subType": "1",            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",            "tradeId": "744876980",            "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
subType	String	Transaction type
tag	String	Order tag
fillPx	String	Last filled price. It is the same as the px from "Get bills details".
fillSz	String	Last filled quantity
side	String	Order side, `buy` `sell`
execType	String	Liquidity taker or maker `T`: taker `M`: maker
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.
~~fillIdxPx~~	~~String~~	~~Index price at the moment of trade execution~~
~~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~~
~~fillPxJpy~~	~~String~~	~~Options price when filled~~
~~fillMarkVol~~	~~String~~	~~Mark volatility when filled~~
~~fillFwdPx~~	~~String~~	~~Forward price when filled~~
~~fillMarkPx~~	~~String~~	~~Mark price when filled~~

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"


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

# 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-JPY`
ordId	String	No	Order ID
subType	String	No	Transaction type `1`: Buy `2`: Sell
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 `ts`. Unix timestamp format in milliseconds, e.g. `1597026383085`
end	String	No	Filter with an end timestamp `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",
    "data": [
        {
            "side": "buy",
            "fillSz": "0.00192834",
            "fillPx": "51858",            "fee": "-0.00000192834",            "ordId": "680800019749904384",
            "feeRate": "-0.001",
            "instType": "SPOT",            "instId": "BTC-JPY",
            "clOrdId": "",            "billId": "680800019754098688",
            "subType": "1",            "tag": "",
            "fillTime": "1708587373361",
            "execType": "T",            "tradeId": "744876980",            "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
subType	String	Transaction type
tag	String	Order tag
fillPx	String	Last filled price
fillSz	String	Last filled quantity
side	String	Order side `buy` `sell`
execType	String	Liquidity taker or maker `T`: taker `M`: maker
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.
~~fillIdxPx~~	~~String~~	~~Index price at the moment of trade execution~~
~~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~~
~~fillPxJpy~~	~~String~~	~~Options price when filled~~
~~fillMarkVol~~	~~String~~	~~Mark volatility when filled~~
~~fillFwdPx~~	~~String~~	~~Forward price when filled~~
~~fillMarkPx~~	~~String~~	~~Mark price when filled~~

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 + tag

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"


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

# 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.

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.

WS / Order channel

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

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": "orders",
      "instType": "SPOT",
      "instId": "BTC-JPY"
    }
  ]
}

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "orders",
      "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 `orders`
> instType	String	Yes	Instrument type `SPOT` `ANY`
> instId	String	No	Instrument ID

Successful Response Example : single

{
    "event": "subscribe",
    "arg": {
        "channel": "orders",
        "instType": "SPOT",
        "instId": "BTC-JPY"
    },
    "connId": "a4d3ae55"
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders",
    "instType": "SPOT"
  },
  "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 `SPOT` `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",
        "instType": "SPOT",
        "instId": "BTC-JPY",
        "uid": "614488474791936"
    },
    "data": [
        {
            "accFillSz": "0.001",
            "algoClOrdId": "",
            "algoId": "",
            "amendResult": "",
            "amendSource": "",
            "avgPx": "31527.1",
            "cancelSource": "",
            "category": "normal",
            "clOrdId": "",
            "code": "0",
            "cTime": "1654084334977",
            "execType": "M",
            "fee": "-0.02522168",
            "feeCcy": "JPY",
            "fillFee": "-0.02522168",
            "fillFeeCcy": "JPY",
            "fillPx": "31527.1",
            "fillSz": "0.001",
            "fillTime": "1654084353263",
            "instId": "BTC-JPY",
            "instType": "SPOT",
            "msg": "",
            "ordId": "452197707845865472",
            "ordType": "limit",
            "px": "31527.1",
            "rebate": "0",
            "rebateCcy": "BTC",
            "reqId": "",
            "side": "sell",
            "attachAlgoClOrdId": "",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "last",
            "source": "",
            "state": "filled",
            "sz": "0.001",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "last",
            "attachAlgoOrds": [],
            "tradeId": "242589207",
            "lastPx": "38892.2",
            "uTime": "1654084353264",
            "isTpLimit": "false",
            "linkedAlgoOrd": {
                "algoId": ""
            }
        }
    ]
}

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
> ordId	String	Order ID
> clOrdId	String	Client Order ID as assigned by the client
> tag	String	Order tag
> px	String	Price
> sz	String	The original order quantity, `SPOT`, in the unit of currency;
> 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, `buy` `sell`
~~> posSide~~	~~String~~	~~Position side~~
> tdMode	String	Trade mode, `cash`: cash
> fillPx	String	Last filled price
> tradeId	String	Last trade ID
> fillSz	String	Last filled quantity The unit is `base_ccy` for SPOT , e.g. BTC-JPY, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`;
> 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.
> 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 , e.g. BTC-JPY, the unit is BTC; For market orders, the unit both is `base_ccy` when the tgtCcy is `base_ccy` or `quote_ccy`;
> avgPx	String	Average filled price. If none is filled, it will return `0`.
> state	String	Order state `canceled` `live` `partially_filled` `filled`
> 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
> tpOrdPx	String	Take-profit order price, it
> slTriggerPx	String	Stop-loss trigger price, it
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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.
>> tpOrdKind	String	TP order kind `condition` `limit`
>> tpTriggerPx	String	Take-profit trigger price.
>> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
>> tpOrdPx	String	Take-profit order price.
>> slTriggerPx	String	Stop-loss trigger price.
>> slTriggerPxType	String	Stop-loss trigger price type. `last`: last 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 TP limit order of one-cancels-the-other order(oco)
>> algoId	Object	Algo ID
> feeCcy	String	Fee currency. For `SPOT`: If you buy, you will receive `base currency`; if you sell, you will receive `quote currency`.
> fee	String	Fee and rebate. For spot, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
> rebateCcy	String	Rebate currency, if there is no rebate, this field is "".
> rebate	String	Rebate accumulated amount, only applicable to spot , 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 "".
> source	String	Order source `7`:The normal order triggered by the `TP/SL order` `13`: The normal order triggered by the algo 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. `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 `20`: Cancel all after triggered. `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
> category	String	Category `normal`
> isTpLimit	String	Whether it is TP limit order. true or false
> 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) 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.
> 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-JPY",
      "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-JPY`
> 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 `optimal_limit_ioc`: Market order with 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	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
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": "",
      "ts":"1695190491421",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1512",
  "op": "order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "",
      "tag": "",
      "ts":"1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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`

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 , market order will be filled with market price .
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.

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-JPY",
      "tdMode": "cash",
      "ordType": "market",
      "sz": "100"
    },
    {
      "side": "buy",
      "instId": "LTC-JPY",
      "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-JPY`
> tdMode	String	Yes	Trade mode Non-Margin 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	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
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": "",
      "ts": "1695190491421",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "",
      "ordId": "12344",
      "tag": "",
      "ts": "1695190491421",
      "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": "",
      "ts": "1695190491421",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "",
      "ordId": "",
      "tag": "",
      "ts": "1695190491421",
      "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": "",
      "ts": "1695190491421",
      "sCode": "5XXXX",
      "sMsg": "Insufficient margin"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "tag": "",
      "ts": "1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY",
      "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",
      "ts": "1695190491421",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1514",
  "op": "cancel-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "ts": "1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY",
      "ordId": "2517748157541376"
    },
    {
      "instId": "LTC-JPY",
      "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",
      "ts": "1695190491421",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "ts": "1695190491421",
      "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",
      "ts": "1695190491421",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "ts": "1695190491421",
      "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",
      "ts": "1695190491421",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "2517748155771904",
      "ts": "1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY",
      "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 and it has to be larger than 0. 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",
      "ts": "1695190491421",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    }
  ],
  "code": "0",
  "msg": "",
  "inTime": "1695190491421339",
  "outTime": "1695190491423240"
}

Failure Response Example

{
  "id": "1512",
  "op": "amend-order",
  "data": [
    {
      "clOrdId": "",
      "ordId": "2510789768709120",
      "ts": "1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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-JPY",
      "ordId": "12345689",
      "newSz": "2"
    },
    {
      "instId": "BTC-JPY",
      "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 and it has to be larger than 0. 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",
      "ts": "1695190491421",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "12344",
      "ts": "1695190491421",
      "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",
      "ts": "1695190491421",
      "reqId": "b12344",
      "sCode": "5XXXX",
      "sMsg": "order not exist"
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "ts": "1695190491421",
      "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",
      "ts": "1695190491421",
      "reqId": "b12344",
      "sCode": "0",
      "sMsg": ""
    },
    {
      "clOrdId": "oktswap7",
      "ordId": "",
      "ts": "1695190491421",
      "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
> ts	String	Timestamp when the order request processing is finished by our system, Unix timestamp format in milliseconds, e.g. `1597026383085`
> 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 oco order, conditional 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-JPY",
    "tdMode":"cash",
    "side":"buy",
    "ordType":"conditional",
    "sz":"2",
    "tpTriggerPx":"15",
    "tpOrdPx":"18"
}

import okx.Trade as Trade

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

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

# One-way stop order
result = tradeAPI.place_algo_order(
    instId="BTC-JPY",
    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-JPY`
tdMode	String	Yes	Trade mode Non-Margin mode `cash`
side	String	Yes	Order side, `buy` `sell`
ordType	String	Yes	Order type `conditional`: One-way stop order `oco`:
sz	String	Conditional	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.
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.

POST / Cancel algo order

Cancel unfilled algo orders. A maximum of 20 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 + Instrument ID

HTTP Request

POST /api/v5/trade/cancel-algos

Request Example

POST /api/v5/trade/cancel-algos
body
[
    {
        "algoId":"590919993110396111",
        "instId":"BTC-JPY"
    },
    {
        "algoId":"590920138287841222",
        "instId":"BTC-JPY"
    }
]

import okx.Trade as Trade

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


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

# Cancel unfilled algo orders (not including Iceberg order, TWAP order, Trailing Stop order)
algo_orders = [
    {"instId": "BTC-JPY", "algoId": "590919993110396111"},
    {"instId": "BTC-JPY", "algoId": "590920138287841222"}
]

result = tradeAPI.cancel_algo_order(algo_orders)
print(result)

Request Parameters

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

Response Example

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

Response Parameters

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

POST / Amend algo order

Amend unfilled algo orders .

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-JPY"
}

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
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
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
newTpTriggerPxType	String	Conditional	Take-profit trigger price type `last`: last price
newSlTriggerPxType	String	Conditional	Stop-loss trigger price type `last`: last 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-JPY",
            "instType": "SPOT",
            "last": "50962.7",            "linkedOrd": {
                "ordId": ""
            },
            "moveTriggerPx": "53423.160",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "",
            "ordType": "move_order_stop",            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",            "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
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
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`
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price
slOrdPx	String	Stop-loss order price.
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`
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
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
~~ccy~~	~~String~~	~~Margin currency~~
~~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.~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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~~
~~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`
~~attachAlgoOrds~~	~~Array of object~~	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
~~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"


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

# 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 For every request, unlike other ordType which only can use one type, `conditional` and `oco` both can be used and separated with comma.
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-JPY`
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",
            "uTime": "1708679675245",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "",
            "instId": "BTC-JPY",
            "instType": "SPOT",
            "last": "51014.6",            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "-1",
            "ordType": "trigger",            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "live",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "100",
            "triggerPxType": "last",
            "triggerTime": "0",
            "linkedOrd":{
                "ordId":"98192973880283",
            },
            "isTradeBorrowMode": "true"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
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
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`
tpTriggerPx	String	Take-profit trigger price
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
tpOrdPx	String	Take-profit order price
slTriggerPx	String	Stop-loss trigger price
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price
slOrdPx	String	Stop-loss order price
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`
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
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
~~ccy~~	~~String~~	~~Margin currency~~
~~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.~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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~~
~~pxVar~~	~~String~~	~~Price ratio~~
~~pxSpread~~	~~String~~	~~Price variance~~
~~szLimit~~	~~String~~	~~Average amount~~
~~pxLimit~~	~~String~~	~~Price Limit~~
~~timeInterval~~	~~String~~	~~Time interval~~
~~callbackRatio~~	~~String~~	~~Callback price ratio~~
~~callbackSpread~~	~~String~~	~~Callback price variance~~
~~activePx~~	~~String~~	~~Active price~~
~~moveTriggerPx~~	~~String~~	~~Trigger price~~
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size.~~
~~quickMgnType~~	~~String~~	~~Quick Margin type, Only applicable to Quick Margin Mode of isolated margin~~
~~attachAlgoOrds~~	~~Array of object~~	~~Attached SL/TP orders info~~
~~isTradeBorrowMode~~	~~String~~	是否自动借币 true：自动借币 false：不自动借币

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"


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

# 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 For every request, unlike other ordType which only can use one type, `conditional` and `oco` both can be used and separated with comma.
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-JPY`
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",
            "uTime": "1708679675245",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "",
            "closeFraction": "",
            "failCode": "",
            "instId": "BTC-JPY",
            "instType": "SPOT",
            "last": "51014.6",            "moveTriggerPx": "",
            "ordId": "",
            "ordIdList": [],
            "ordPx": "-1",
            "ordType": "oco",            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "",
            "state": "canceled",
            "sz": "10",
            "szLimit": "",
            "tag": "",
            "tdMode": "cash",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "100",
            "triggerPxType": "last",
            "triggerTime": "",
            "linkedOrd":{
                "ordId":"98192973880283",
            },
            "isTradeBorrowMode": "true"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
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
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`
tpTriggerPx	String	Take-profit trigger price.
tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
tpOrdPx	String	Take-profit order price.
slTriggerPx	String	Stop-loss trigger price.
slTriggerPxType	String	Stop-loss trigger price type. `last`: last price
slOrdPx	String	Stop-loss order price.
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`
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
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
~~ccy~~	~~String~~	~~Margin currency~~
~~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.~~
~~lever~~	~~String~~	~~Leverage, from `0.01` to `125`.~~
~~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~~
~~pxVar~~	~~String~~	~~Price ratio~~
~~pxSpread~~	~~String~~	~~Price variance~~
~~szLimit~~	~~String~~	~~Average amount~~
~~pxLimit~~	~~String~~	~~Price Limit~~
~~timeInterval~~	~~String~~	Time interval Only applicable to `twap` order
~~callbackRatio~~	~~String~~	~~Callback price ratio~~
~~callbackSpread~~	~~String~~	~~Callback price variance~~
~~activePx~~	~~String~~	~~Active price~~
~~moveTriggerPx~~	~~String~~	~~Trigger price~~
~~reduceOnly~~	~~String~~	~~Whether the order can only reduce the position size.~~
~~quickMgnType~~	~~String~~	Quick Margin type, Only applicable to Quick Margin Mode of isolated margin `manual`, `auto_borrow`, `auto_repay`
~~attachAlgoOrds~~	~~Array of object~~	Attached SL/TP orders info Applicable to `Spot and futures mode/Multi-currency margin/Portfolio margin`
~~isTradeBorrowMode~~	~~String~~	是否自动借币 true：自动借币 false：不自动借币

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": "SPOT",
      "instId": "BTC-JPY"
    }
  ]
}

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "orders-algo",
      "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 `orders-algo`
> instType	String	Yes	Instrument type `SPOT` `ANY`
> instId	String	No	Instrument ID

Successful Response Example : single

{
  "event": "subscribe",
  "arg": {
    "channel": "orders-algo",
    "instType": "SPOT",
    "instId": "BTC-JPY"
  },
  "connId": "a4d3ae55"
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders-algo",
    "instType": "SPOT",
    "instId": "BTC-JPY"
  },
  "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 `SPOT` `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": "SPOT",
        "instId": "BTC-JPY"
    },
    "data": [{
        "actualPx": "0",
        "actualSide": "",
        "actualSz": "0",
        "algoClOrdId": "",
        "algoId": "581878926302093312",
        "attachAlgoOrds": [],
        "amendResult": "",
        "cTime": "1685002746818",
        "uTime": "1708679675245",
        "clOrdId": "",
        "failCode": "",
        "instId": "BTC-JPY",
        "instType": "SPOT",
        "last": "26174.8",
        "notionalJPY": "11.0",
        "ordId": "",
        "ordIdList": [],
        "ordType": "conditional",
        "reqId": "",
        "side": "buy",
        "slOrdPx": "",
        "slTriggerPx": "",
        "slTriggerPxType": "",
        "state": "live",
        "sz": "11",
        "tag": "",
        "tdMode": "cash",
        "tgtCcy": "quote_ccy",
        "tpOrdPx": "-1",
        "tpTriggerPx": "1",
        "tpTriggerPxType": "last",
        "amendPxOnTriggerType": "0",
        "linkedOrd":{
                "ordId":"98192973880283"
        }
    }]
}

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
> ordId	String	Latest order ID, the order ID associated with the algo order. 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. The value is the quantity in base currency.
> ordType	String	Order type `conditional`: One-way stop order `oco`: One-cancels-the-other order `trigger`: Trigger order
> side	String	Order side `buy` `sell`
> tdMode	String	Trade mode `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
> state	String	Order status `live`: to be effective `effective`: effective `canceled`: canceled `order_failed`: order failed `partially_failed`: partially failed `partially_effective`: partially effective
> tpTriggerPx	String	Take-profit trigger price.
> tpTriggerPxType	String	Take-profit trigger price type. `last`: last price
> tpOrdPx	String	Take-profit order price.
> slTriggerPx	String	Stop-loss trigger price.
> slTriggerPxType	String	Stop-loss trigger price type. `last`: last price
> slOrdPx	String	Stop-loss order price.
> last	String	Last filled price while placing
> actualSz	String	Actual order quantity
> actualPx	String	Actual order price
> notionalJPY	String	Estimated national value in `JPY` 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`
> 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;
> algoClOrdId	String	Client Algo Order ID as assigned by the client.
> 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`
>> 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
>> 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
>> 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

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


marketDataAPI =  MarketData.MarketAPI()

# 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":"PEPE-JPY",
       "last":"0.003",
       "lastSz":"0",
       "askPx":"",
       "askSz":"0",
       "bidPx":"0.003",
       "bidSz":"70998",
       "open24h":"0.003",
       "high24h":"0.003",
       "low24h":"0.003",
       "volCcy24h":"0",
       "vol24h":"0",
       "ts":"1747102886012",
       "sodUtc0":"0.003",
     },
     {
         "instType":"SPOT",
         "instId":"XRP-JPY",
         "last":"481",
         "lastSz":"1",
         "askPx":"",
         "askSz":"0",
         "bidPx":"481",
         "bidSz":"2",
         "open24h":"481",
         "high24h":"481",
         "low24h":"481",
         "volCcy24h":"0",
         "vol24h":"0",
         "ts":"1747102920011",
         "sodUtc0":"481",
         "sodUtc8":"481"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size. 0 represents there is no trading volume
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, with a unit of `currency`. The value is the quantity in quote currency.
vol24h	String	24h trading volume, with a unit of `contract`. 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-JPY

import okx.MarketData as MarketData


marketDataAPI =  MarketData.MarketAPI()

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

Request Parameters

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

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
           "instType":"SPOT",
           "instId":"BTC-JPY",
           "last":"480",
           "lastSz":"0.01",
           "askPx":"",
           "askSz":"0",
           "bidPx":"480",
           "bidSz":"773.9599",
           "open24h":"480",
           "high24h":"480",
           "low24h":"480",
           "volCcy24h":"0",
           "vol24h":"0",
           "ts":"1747112880014",
           "sodUtc0":"480",
           "sodUtc8":"480"
        }
  ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size. 0 represents there is no trading volume
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, with a unit of `currency`. The value is the quantity in quote currency.
vol24h	String	24h trading volume, with a unit of `contract`. 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-JPY

import okx.MarketData as MarketData


marketDataAPI =  MarketData.MarketAPI()

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

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-JPY`
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 / Full order book

Retrieve order book of the instrument. The data will be updated once a second.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/books-full

Request Example

GET /api/v5/market/books-full?instId=BTC-JPY&sz=1

Request Parameters

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

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "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-JPY

import okx.MarketData as MarketData


marketDataAPI =  MarketData.MarketAPI()

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

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-JPY`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H] Japan 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, with a unit of `contract`. The value is the quantity in base currency.
volCcy	String	Trading volume, with a unit of `currency`. 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 JPY for BTC-JPY
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-JPY

import okx.MarketData as MarketData


marketDataAPI =  MarketData.MarketAPI()

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

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-JPY`
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] Japan 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, with a unit of `contract`. The value is the quantity in base currency.
volCcy	String	Trading volume, with a unit of `currency`. 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 JPY for BTC-JPY ;
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-JPY

import okx.MarketData as MarketData


marketDataAPI =  MarketData.MarketAPI()

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

Request Parameters

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

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-JPY",
            "side": "sell",
            "sz": "0.00001",
            "px": "29963.2",
            "tradeId": "242720720",
            "ts": "1654161646974"
        },
        {
            "instId": "BTC-JPY",
            "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 / 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


marketDataAPI =  MarketData.MarketAPI()

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

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
     {
         "volJpy": "34462818865189",
         "ts": "1657856040389"
     }
  ]
}

Response Parameters

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

GET / Call auction details

Retrieve call auction details.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/call-auction-details

Request Example

GET /api/v5/market/call-auction-details?instId=BTC-JPY

Request Parameters

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

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "instId": "BTC-JPY",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
eqPx	String	Equilibrium price
matchedSz	String	Matched size for both buy and sell The unit is in base currency
unmatchedSz	String	Unmatched size
auctionEndTime	String	Call auction end time. Unix timestamp in milliseconds.
state	String	Trading state of the symbol `call_auction` `continuous_trading`
ts	String	Data generation time. Unix timestamp in millieseconds.

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-JPY"
    }
  ]
}

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-JPY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"tickers\", \"instId\" : \"BTC-JPY\"}]}",
  "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-JPY"
  },
  "data": [
    {
      "instType": "SPOT",
      "instId": "BTC-JPY",
      "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. 0 represents there is no trading volume
> 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, with a unit of `currency`. The value is the quantity in quote currency.
> vol24h	String	24h trading volume, with a unit of `contract`. 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-JPY"
    }
  ]
}

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-JPY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"candle1D\", \"instId\" : \"BTC-JPY\"}]}",
  "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-JPY"
  },
  "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, with a unit of `contract`. The value is the quantity in base currency.
> volCcy	String	Trading volume, with a unit of `currency`. 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 `JPY` for `BTC-JPY`
> 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-JPY"
    }
  ]
}

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-JPY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades\", \"instId\" : \"BTC-JPY\"}]}",
  "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-JPY"
  },
  "data": [
    {
      "instId": "BTC-JPY",
      "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-JPY`
> 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-JPY"
    }
  ]
}

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-JPY"
    },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades-all\", \"instId\" : \"BTC-JPY\"}]}",
  "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-JPY"
  },
  "data": [
    {
      "instId": "BTC-JPY",
      "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-JPY`
> 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-JPY"
    }
  ]
}

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-JPY"
  },
  "connId": "a4d3ae55"
}

Failure example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"books\", \"instId\" : \"BTC-JPY\"}]}",
  "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-JPY"
  },
  "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-JPY"
  },
  "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, OKJ 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": "BTC-JPY"
  },
  "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": "BTC-JPY"
  },
  "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": "BTC-JPY",
      "ts": "1670324386802",
      "seqId": 363996337
    }
  ]
}

WS / Call auction details channel

Retrieve call auction details.

URL Path

/ws/v5/public

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "call-auction-details",
        "instId": "BTC-JPY"
    }]
}

Request Parameters

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

Successful Response Example

{
  "event": "subscribe",
  "arg": {
      "channel": "call-auction-details",
      "instId": "BTC-JPY"
    },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"call-auction-details\", \"instId\" : \"BTC-JPY\"}]}",
  "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": "call-auction-details",
    "instId": "ONDO-USDC"
  },
  "data": [
        {
            "instId": "BTC-JPY",
            "unmatchedSz": "9988764",
            "eqPx": "0.6",
            "matchedSz": "44978",
            "state": "continuous_trading",
            "auctionEndTime": "1726542000000",
            "ts": "1726542000007"
        }
  ]
}

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
> eqPx	String	Equilibrium price
> matchedSz	String	Matched size for both buy and sell The unit is in base currency
> unmatchedSz	String	Unmatched size
> auctionEndTime	String	Call auction end time. Unix timestamp in milliseconds.
> state	String	Trading state of the symbol `call_auction` `continuous_trading`
> ts	String	Data generation time. Unix timestamp in millieseconds.

Funding Account

The API endpoints of Funding Account require authentication.

REST API

Get Balance

This retrieves information on the balances of all the assets, and the amount that is available or on hold.

Rate Limit: 6 requests/s

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/wallet

Request Example

GET /api/v5/asset/wallet

import okx.Funding as Funding

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

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

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

# Get funding account balance
result = fundingAPI.get_balance()
print(result)

Response Result

[
    {
        "available":"37.11827078",
        "balance":"37.11827078",
        "currency":"ETH",
        "hold":"0"
    },
    {
        "available":"0",
        "balance":"0",
        "currency":"BTC",
        "hold":"0"
    }
]

Response Parameters

Parameter	Type	Description
currency	String	Token symbol, e.g. `BTC`
balance	String	Remaining balance
hold	String	Amount on hold (unavailable)
available	String	Amount available

Get Currency

This retrieves information for a single token in your account, including the remaining balance, and the amount available or on hold.

Rate Limit: 6 requests/s

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/wallet/<currency>

Request Example

GET /api/v5/asset/wallet/XMR

import okx.Funding as Funding

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

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

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

# Get funding account balance
result = fundingAPI.get_balance_by_currency(
    currency="XMR"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	Yes	Token symbol, e.g. `BTC`

Response Result

[{
    "balance":"300.00000000",
    "available":"300.00000000",
    "hold":"0.00000000"
}]

Response Parameters

Parameter	Type	Description
balance	String	Remaining balance
hold	String	Amount on hold (unavailable)
available	String	Amount available

Get Currencies

This retrieves a list of all currencies. Not all currencies can be traded. Currencies that have not been defined in ISO 4217 may use a custom symbol.

Rate Limit: 6 requests/s

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"  # Live trading: 0, Demo trading: 1

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

# Get currency list
result = fundingAPI.get_currencies()
print(result)

Response Result

[
    {
        "can_deposit":"1",
        "can_withdraw":"1",
        "currency":"PLT",
        "chain":"Palette(pPLT)",
        "min_withdrawal":"0.1",
        "name":""
    },
    {
        "can_deposit":"1",
        "can_withdraw":"1",
        "currency":"PLT",
        "chain":"Ethereum(ePLT)",
        "min_withdrawal":"0.1",
        "name":""
    }
]

Response Parameters

Parameter	Type	Description
currency	String	Token symbol, e.g. `BTC`
chain	String	Chain name
name	String	Token name
can_deposit	String	String Availability to deposit, `0` = not available，`1` = available
can_withdraw	Boolean	Availability to withdraw, `0` = not available，`1` = available
min_withdrawal	Boolean	Minimum withdrawal threshold

Get Asset Valuation

Get the valuation of the total assets of the account in btc or fiat currency.

Rate Limit: 1 request per 30 seconds

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"  # Live 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

Parameter	Type	Required	Description
account_type	String	No	Line of Business Type `0`Total account assets `18`Trading Account `6`Funding Account. Query total assets by default

Response Result

{
    "account_type": "0",
    "balance": 0.00878181,
    "valuation_currency": "JPY",
    "timestamp": "2019-12-09T10:28:23.002Z"
}

Response Parameters

Parameter	Type	Description
valuation_currency	String	The valuation according to a certain fiat currency is JPY
balance	String	Estimated assets
timestamp	String	Data return time
account_type	String	Line of Business Type `0`Total account assets `18`Trading Account `6`Funding Account Query total assets by default

Funds Transfer

This endpoint supports the transfer of funds among your funding account, trading accounts.

Rate Limit: 1 request per 2 seconds

Rate Limit Rule: UserID + Currency

HTTP Request

POST /api/v5/asset/transfer

Request Example

# Transfer 1.5 BTC from funding account to trading account
POST /api/v5/asset/transfer
body
{
    "currency":"btc",
    "amt":"1.5",
    "from":"6",
    "to":"18"
}

import okx.Funding as Funding

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

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

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

# Funds Transfer
result = fundingAPI.transfer(
    currency="BTC",
    amount="1.5",
    from_="6",
    to="18"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	No	Token symbol, e.g. `BTC`
amount	String	Yes	Amount to be transferred
from	String	Yes	Remitting account (18: Trading Account 6: Funding Account )
to	String	Yes	Receiving account(18:Trading Account 6: Funding Account )

Response Result

{
    "transfer_id": "754147",
    "currency": "LTC",
    "from": "6",
    "amount": "0.1",
    "to": "1",
    "result": true
}

Response Parameters

Parameter	Type	Description
transfer_id	String	Transfer ID
currency	String	Token to be transferred
from	String	The remitting account
amount	String	Transfer amount
to	String	The beneficiary account
result	String	Transfer result. An error code will be displayed if it failed.

Bills Details

This retrieves the account bills dating back the past month. Pagination is supported and the response is sorted with most recent first in reverse chronological order.

Rate Limit: 20 requests per 2 seconds

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/ledger

Request Example

GET /api/v5/asset/ledger?type=2&currency=btc&after=9260348&limit=10

import okx.Funding as Funding

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

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

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

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

Request Parameters

Parameter	Type	Required	Description
currency	String	No	The token symbol, e.g. `BTC`. Complete account statement for will be returned if the field is left blank
type	String	No	`1`:deposit `2`:withdrawal `13`:cancel withdrawal `37`: into spot account `38`: out of spot account
after	String	No	Pagination of data to return records earlier than the requested `ledger_id`
before	String	No	Pagination of data to return records newer than the requested `ledger_id`
limit	String	No	Number of results per request. The maximum is `100`; the default is `100`

Response Result

[
    {
        "amount":"-0.00100941",
        "balance":"0",
        "currency":"BTC",
        "fee":"0",
        "ledger_id":"9260348",
        "timestamp":"2018-10-19T01:12:21.000Z",
        "type":"To trading account"
    },
    {
        "amount":"0.00051843",
        "balance":"0.00100941",
        "currency":"BTC",
        "fee":"0",
        "ledger_id":"8987285",
        "timestamp":"2018-10-12T11:01:14.000Z",
        "type":"Get from activity"
    }
]

Response Parameters

Parameter	Type	Description
ledger_id	String	Bill ID
currency	String	Token symbol
balance	String	Remaining balance
amount	String	Amount changed
type	String	Type of bills
fee	String	Service fees
timestamp	String	Creation time

Get Bank Card List

Get all bank card information bound to the user

Rate Limit: 6 requests/s

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/bank-card-list

Request Example

GET /api/v5/asset/bank-card-list

import okx.Funding as Funding

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

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

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

# Get user bank card list
result = fundingAPI.get_bank_card()
print(result)

Response Example

[
    {
         "bank_card_id": "1",
         "card_number": "123456",
         "bank_name": "PayPay銀行",
         "branch_name": "はやぶさ支店",
         "available": true
    },
    {
         "bank_card_id": "2",
         "card_number": "123457",
         "bank_name": "PayPay銀行",
         "branch_name": "はやぶさ支店",
         "available": true
    }
]

Response Parameters

Parameter Name	Type	Description
bank_card_id	String	Bank card ID
card_number	String	Bank card number
bank_name	String	Bank name
branch_name	String	Bank branch name
available	Boolean	Available，false:not available，true:available

Fiat Withdrawal

This endpoint supports the withdrawal of Japanese Yen. By default, funds will be withdrawn to the bank card used in the last withdrawal. If this card is unavailable, the withdrawal will be redirected to the most recently added or modified bank card.

Rate Limit: 1 requests per 120 seconds

Rate Limit Rule: UserID

HTTP Request

POST /api/v5/asset/jpywithdrawal

Request Example

POST /api/v5/asset/jpywithdrawal
body
{
    "amount":"10000",
    "trade_pwd":"123456",
    "bank_card_id":"1"
}

import okx.Funding as Funding

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

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

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

# Fiat Withdrawal
result = fundingAPI.fiat_withdraw(
    amount="10000",
    trade_pwd="123456",
    bank_card_id="1"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
amount	String	Yes	Withdrawal amount
trade_pwd	String	Yes	Fund password
bank_card_id	String	No	Cash withdrawal bank card id

Response Result

{
    "amount":"10000",
    "withdraw_id":2412031209191611,
    "result":true
}

Response Parameters

Parameter	Type	Description
amount	String	Withdrawal amount
withdraw_id	String	Withdrawal ID
result	String	withdrawal result. An error code will be displayed if it failed

Fiat Withdrawal History

This retrieves the withdrawal records of Japanese Yen.

Rate Limit: 6 requests per second

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/jpywithdrawal/history

Request Example

GET /api/v5/asset/jpywithdrawal/history

import okx.Funding as Funding

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

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

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

# Withdrawal Record Query
result = fundingAPI.fiat_withdraw_history()
print(result)

Response Result

[
    {
        "amount":"10000",
        "withdraw_id":2412031209191611,
        "fee":"400",
        "status":"1",
        "timestamp":"2018-09-30T02:49:29.001Z"
    },
    {
        "amount":"19800",
        "withdraw_id":2412031158328186,
        "fee":"400",
        "status":"4",
        "timestamp":"2018-09-28T01:09:19.022Z"
    }
]

Response Parameters

Parameter	Type	Description
amount	String	Withdrawal amount
withdraw_id	String	Withdrawal ID
fee	String	Withdrawal fee
status	String	Withdrawal status `1`: Waiting for processing `2`: Withdrawal in Progress `4`: Success `5`: Cancellation in Progress `6`: Cancelled `7`: Unsuccessful to withdraw `8`: TFS refund `9`: Disabled
timestamp	String	Time the withdrawal request was submitted

Notes

Up to 100 recent withdrawal records will be returned.

Fiat Deposit History

This retrieves the deposit history of Japanese Yen.

Rate Limit: 6 requests per second

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/jpyDeposit/history

Request Example

GET /api/v5/asset/jpyDeposit/history

import okx.Funding as Funding

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

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

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

# This retrieves the deposit history of Japanese Yen
result = fundingAPI.fiat_deposit_history()
print(result)

Response Result

[
    {
        "amount":"10000",
        "status":"1",
        "timestamp":"2019-11-30T02:39:29.012Z"
    },
    {
        "amount":"7800",
        "status":"4",
        "timestamp":"2019-10-21T02:04:49.122Z"
    }
]

Response Parameters

Parameter	Type	Description
amount	String	Deposit amount
status	String	Deposit status 1: Awaiting processing 2: Processing 4: Success 8: Refund processed
timestamp	String	Time that the deposit is credited

Notes

Up to 100 recent deposit records will be returned.

Withdrawal

This endpoint supports the withdrawal of tokens

Rate Limit: 1 requests per 10 seconds

Rate Limit Rule: UserID

HTTP Request

POST /api/v5/asset/withdrawal

Request Example

POST /api/v5/asset/withdrawal
body
{
    "amount":"1",
    "fee":"0.0005",
    "trade_pwd":"123456",
    "currency":"BTC",
    "to_address":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw",
    "usage_agreement":"1",
    "reason":"2"
}

import okx.Funding as Funding

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

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

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

# Withdrawal
result = fundingAPI.coin_withdraw(
    currency="PEPE",
    amount="100",
    destination="-1",
    to_address="0x730dfca513a58be208fbe27c2dc00fa423626ebf",
    trade_pwd="123456",
    fee="0.5",
    reason="1",
    usage_agreement="1"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	Yes	Token symbol, e.g. `BTC`
amount	String	Yes	Withdrawal amount
destination	String	Yes	Withdrawal address: `-1`:digital currency address `5`:OKCoinJapan
to_address	String	Yes	Trusted digital currency address or email that already in your address book. Some digital currency addresses are formatted as `address:tag`, e.g. `ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456`
trade_pwd	String	Yes	Fund password
fee	String	Optional	Network transaction fee. Please refer to the withdrawal fees section below for recommended fee amount. Must be set in increments of `0.0001`. Specify `0` when destination is `5`
chain	String	Optional	Chain name. There are multiple chains under some currencies, such as PLT has Palette(pPLT) and Ethereum(ePLT). You have to make a distinction. If currency has multiply chains, this parameter must be filled.
usage_agreement	Object	Optional	Specify 1 to agree that this withdrawal address is NOT from our list of forbidden countries nor controlled by foreign PEPs. About our list of forbidden countries About foreign PEPs
reason	String	Yes	Reason for Withdrawal. `1`: Sending to my external wallet `2`: Investment・asset utilization `3`: Living expenses `4`: Tuition fee `5`: Travel expenses `6`: Salary `7`: Business consignment fee `8`: Condolence money・congratulatory money・gifts `9`: Donation `10`: Service fee `11`: (Domestic)Merchandise Purchase `12`: Payment for imports and intermediary trade `99`: Others

Notes

If you select Payment for imports and intermediary trade, or Others, it may take some time to complete the withdrawal because we need to confirm more detailed information.

Response Result

{
    "amount":"0.1",
    "withdraw_id":67485,
    "currency":"BTC",
    "chain":"BTC",
    "result":true
}

Response Parameters

Parameter	Type	Description
currency	String	Token symbol, e.g. `BTC`
chain	String	chain name
amount	String	Withdrawal amount
withdraw_id	String	Withdrawal ID
result	String	withdrawal result. An error code will be displayed if it failed

Withdrawal History

This retrieves up to 100 recent withdrawal records.

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

import okx.Funding as Funding

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

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

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

# Get withdrawal history
result = fundingAPI.get_coins_withdraw_record()
print(result)

Request Parameters

Response Result

[
    {
        "withdraw_id":"1",
        "amount":"0.094",
        "fee":"0.01000000eth",
        "txid":"0x62477bac6509a04512819bb1455e923a60dea5966c7caeaa0b24eb8fb0432b85",
        "currency":"ETH",
        "chain":"ETH",
        "from":"13426335357",
        "to":"0xA41446125D0B5b6785f6898c9D67874D763A1519",
        "timestamp":"2018-04-22T23:09:45.000Z",
        "status":"2"
    },
    {
        "withdraw_id":"2",
        "amount":"0.01",
        "fee":"0.00000000btc",
        "txid":"",
        "currency":"BTC",
        "chain":"BTC",
        "from":"13426335357",
        "to":"13426335357",
        "timestamp":"2018-05-17T02:43:08.000Z",
        "status":"4"
    }
]

Response Parameters

Parameter	Type	Description
withdraw_id	String	withdraw id
currency	String	Token symbol, e.g. `BTC`
amount	String	Token amount
timestamp	String	Time the withdrawal request was submitted
status	String	Status of withdrawal. `1`: Awaiting withdrawal `2`: Withdrawal in Progress `3`: CS Reviewing `4`: Withdrawal Completed `5`: Cancellation in Progress `6`: Cancelled `7`: Withdrawal Failed `8`: Refunded
from	String	Remitting address (User phone number or email will be shown for OKCoinJapan addresses)
to	String	Receiving address
tag	String	Some tokens require a tag for withdrawals. This is not returned if not required
txId	String	Hash record of the withdrawal. This parameter will not be returned for internal transfers
fee	String	Withdrawal fee
chain	String	Chain name

Withdrawal History of a Currency

This retrieves the withdrawal records of a specific currency

Rate Limit: 6 requests per second

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/withdrawal/history/<currency>

Request Example

GET /api/v5/asset/withdrawal/history/btc

import okx.Funding as Funding

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

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

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

# 获取单个币种提币记录
result = fundingAPI.get_coin_withdraw_record(
    currency="BTC"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	Yes	Token symbol

Response Result

[
    {
        "withdraw_id":"1",
        "amount":"0.01105486",
        "fee":"0.00000000btc",
        "currency":"BTC",
        "chain":"BTC",
        "txid": "66602e279569ba319a929f5bda731d228962bc67cd89dfa0d432d82722681d66",
        "from":"13426335357",
        "to":"13426335357",
        "timestamp":"2018-09-30T02:49:29.000Z",
        "status": "2"
    },
    {
        "withdraw_id":"2",
        "amount":"0.01144408",
        "fee":"0.00000000btc",
        "currency":"BTC",
        "chain":"BTC",
        "txid": "66602e279569ba319a929f5bda731d228962456475467d89dfa0d432d82722681d66",
        "from":"13426335357",
        "to":"13426335357",
        "timestamp":"2018-09-18T00:44:56.000Z",
        "status": "2"
    }
]

Response Parameters

Parameter	Type	Description
withdraw_id	String	Withdrawal ID
amount	String	Withdrawal amount
timestamp	String	Time the withdrawal request was submitted
currency	String	Token symbol, e.g. `BTC`
status	String	Status of withdrawal `1`: Awaiting withdrawal `2`: Withdrawal in Progress `3`: CS Reviewing `4`: Withdrawal Completed `5`: Cancellation in Progress `6`: Cancelled `7`: Withdrawal Failed `8`: Refunded
from	String	Remitting address (User phone number or email will be shown for OKCoinJapan addresses)
to	String	Receiving address
tag	String	Some tokens require a tag for withdrawals. This is not returned if not required
txId	String	Hash record of the withdrawal. This parameter will not be returned for internal transfers
fee	String	withdrawal fee
chain	String	Chain name

Notes

When the remitting account is an OKCoinJapan account, the user phone number or email is shown instead of the digital currency address. If the receiving account is also an OKCoinJapan account, the txid will not be returned.

Up to 100 recent withdrawal records will be returned.

Please note that the transactions shown may not be confirmed on the blockchain yet. Please be patient if the funds have not arrived at the receiving address.

Deposit Address

This retrieves the deposit addresses of currencies, including previously used addresses

Rate Limit: 20 requests per 2 seconds

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/deposit/address

Request Example

GET /api/v5/asset/deposit/address?currency=btc

import okx.Funding as Funding

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

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

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

# Get deposit address information
result = fundingAPI.get_deposit_address(
    currency="BTC"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	Yes	Token symbol, e.g. `BTC`

Response Result

[
    {
        "address": "2Mti44L7thuxyzYiGzZyCcm9R7d7jgGwzZK",
        "chain": "BTC"
    }
]

Response Parameters

Parameter	Type	Description
address	String	Deposit address
tag	String	Deposit tag (This will not be returned if the token does not require a tag for deposit)
chain	String	Chain name

Explanation

Tag or payment ID are required for some tokens. Please include them while making deposits to ensure the your funds will be properly credited.

Deposit History

This retrieves the deposit history of all currencies, up to 100 recent records.

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

import okx.Funding as Funding

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

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

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

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

Response Result

[
    {
        "amount":"0.01044408",
        "txid":"1915737_3_0_0_WALLET",
        "currency":"BTC",
        "chain":"BTC",
        "deposit_id":"1",
        "to":"",
        "timestamp":"2018-09-30T02:45:50.000Z",
        "status":"1"
    },
    {
        "amount":"491.6784211",
        "txid":"1744594_3_184_0_WALLET",
        "currency":"BTC",
        "chain":"BTC",
        "deposit_id":"2",
        "to":"",
        "timestamp":"2018-08-21T08:03:10.000Z",
        "status":"2"
    },
    {
        "amount":"223.18782496",
        "txid":"6d892c669225b1092c780bf0da0c6f912fc7dc8f6b8cc53b003288624c",
        "currency":"ETH",
        "chain":"ETH",
        "deposit_id":"3",
        "to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
        "timestamp":"2018-08-17T09:18:40.000Z",
        "status":"4"
    }
]

Response Parameters

Parameter	Type	Description
currency	String	Token Symbol, e.g. `BTC`
deposit_id	String	Deposit ID
amount	String	Deposit amount
to	String	Deposit address
tag	String	Some tokens require a tag for deposit. This is not returned if not required
txid	String	Hash record of the deposit
timestamp	String	Time that the deposit is credited
status	String	Status of deposit `1`: Waiting confirmation `2`: Deposit confirmation `3`: CS Reviewing `4`: Success `7`: Deposit Failed
chain	String	Chain name

Deposit History of a Currency

This retrieves the deposit history of a specific currency, up to 100 recent deposit records will be returned.

Rate Limit: 6 requests per second

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/deposit/history/<currency>

Request Example

GET /api/v5/asset/deposit/history/btc

import okx.Funding as Funding

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

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

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

# Get deposit records
result = fundingAPI.get_deposit_history_by_currency(
    currency="BTC"
)
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	No	Token Symbol

Response Result

[
    {
        "amount":"0.0835",
        "currency":"BTC",
        "chain":"BTC",
        "deposit_id":"1",
        "txid":"6d892c669225b1092c780bf0da0c6f912fc3e8f997dc8f6b8cc53b003288624c",
        "to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
        "timestamp":"2018-06-09T07:57:09.000Z",
        "status":"2"
    },
    {
        "amount":"0.01",
        "currency":"BTC",
        "chain":"BTC",
        "deposit_id":"2",
        "txid":"590426_1_0_WALLET",
        "to":"",
        "timestamp":"2018-05-30T01:33:40.000Z",
        "status":"2"
    }
]

Response Parameters

Parameter	Type	Description
currency	String	Token Symbol
deposit_id	String	Deposit ID
amount	String	Deposit amount
to	String	Deposit address
tag	String	Some tokens require a tag for deposit. This is not returned if not required
txid	String	Hash record of the deposit
timestamp	String	Time that the deposit is credited
status	String	Status of deposit `1`: Waiting confirmation `2`: Deposit confirmation `3`: CS Reviewing `4`: Success `7`: Deposit Failed
chain	String	Chain name

Withdrawal Fees

This retrieves the information about the recommended network transaction fee for withdrawals to digital currency addresses. The higher the fees are set, the faster the confirmations.

Rate Limit: 6 requests per second

Rate Limit Rule: UserID

HTTP Request

GET /api/v5/asset/withdrawal/fee

Request Example

GET /api/v5/asset/withdrawal/fee?currency=btc

import okx.Funding as Funding

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

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

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

# Get withdrawal fees
result = fundingAPI.get_coin_fee()
print(result)

Request Parameters

Parameter	Type	Required	Description
currency	String	No	Token symbol, e.g. `BTC`, if left blank, information for all tokens will be returned

Response Result

[
    {
        "currency":"BTC",
        "chain":"BTC",
        "max_fee":"0.02",
        "min_fee":"0.0005"
    },
    {
        "currency":"LTC",
        "chain":"LTC",
        "max_fee":"0.2",
        "min_fee":"0.001"
    },
    {
        "currency":"ETH",
        "chain":"ETH",
        "max_fee":"0.2",
        "min_fee":"0.01"
    }
]

Response Parameters

Parameter	Type	Description
currency	String	Token symbol
chain	String	Chain name
min_fee	String	Minimum withdrawal fee
max_fee	String	Maximum withdrawal fee

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": "",
            "auctionEndTime": "",
            "baseCcy": "BTC",
            "category": "1",
            "expTime": "",
            "instId": "BTC-JPY",
            "instType": "SPOT",
            "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",
            "quoteCcy": "JPY",
            "state": "live",
            "ruleType": "normal",
            "tickSz": "0.1"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID, e.g. `BTC-JPY`
category	String	Currency category. Note: this parameter is already deprecated
baseCcy	String	Base currency, e.g. `BTC` in `BTC-JPY`
quoteCcy	String	Quote currency, e.g. `JPY` in `BTC-JPY`
listTime	String	Listing time, Unix timestamp format in milliseconds, e.g. `1597026383085`
auctionEndTime	String	The end time of call auction, Unix timestamp format in milliseconds, e.g. `1597026383085` Only applicable to `SPOT` that are listed through call auctions, return "" in other cases
expTime	String	Expiry time. It is the instrument offline time when there is a manual offline. Update once change.
tickSz	String	Tick size, e.g. `0.0001`
lotSz	String	Lot size. The value is the quantity in `base currency`.
minSz	String	Minimum order size. The value is the quantity in `base currency`.
alias	String	Alias
state	String	Instrument status `live` `suspend` `preopen` `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. The value is the quantity in `base currency`.
maxMktSz	String	The maximum order quantity of a single market order. The value is the quantity in `JPY`.
maxLmtAmt	String	Max JPY amount for a single limit order
maxMktAmt	String	Max JPY amount for a single market order
maxTwapSz	String	The maximum order quantity of a single TWAP order. 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. The value is the quantity in `base currency`.
maxTriggerSz	String	The maximum order quantity of a single trigger order. The value is the quantity in `base currency`.
maxStopSz	String	The maximum order quantity of a single stop market order. The value is the quantity in `JPY`.

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`

WebSocket

Instruments channel

The instruments will be pushed if there is any change to the instrument’s state (such as listing of new trading pairs, trading suspension, etc.).

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": "",
        "auctionEndTime": "",
        "baseCcy": "BTC",
        "category": "1",
        "expTime": "",
        "instId": "BTC-JPY",
        "instType": "SPOT",
        "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",
        "quoteCcy": "JPY",
        "state": "live",
        "ruleType": "normal",
        "tickSz": "0.1"
    }
  ]
}

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-JPY`
> baseCcy	String	Base currency, e.g. `BTC` in `BTC-JPY`
> quoteCcy	String	Quote currency, e.g. `JPY` in `BTC-JPY`
> listTime	String	Listing time
> auctionEndTime	String	The end time of call auction, Unix timestamp format in milliseconds, e.g. `1597026383085` Only applicable to `SPOT` that are listed through call auctions, return "" in other cases
> expTime	String	Expiry time. It can also be the delisting time of the trading instrument. Update once change.
> tickSz	String	Tick size, e.g. `0.0001`
> lotSz	String	Lot size. The value is the quantity in `base currency`.
> minSz	String	Minimum order size. The value is the quantity in `base currency`.
> alias	String	Alias
> state	String	Instrument status `live` `suspend` `expired` `preopen` `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. The value is the quantity in `base currency`.
> maxMktSz	String	The maximum order quantity of a single market order. The value is the quantity in `JPY`.
> maxTwapSz	String	The maximum order quantity of a single TWAP order. The value is the quantity in `base currency`.
> maxIcebergSz	String	The maximum order quantity of a single iceBerg order. The value is the quantity in `base currency`.
> maxTriggerSz	String	The maximum order quantity of a single trigger order. The value is the quantity in `base currency`.
> maxStopSz	String	The maximum order quantity of a single stop market order. The value is the quantity in `JPY`.

Price limit channel

Retrieve the maximum buy price and minimum sell price of instruments. Data will be pushed every second when there are changes in limits, and will not be pushed when there is no changes on limit.

URL Path

/ws/v5/public

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "price-limit",
      "instId": "BTC-JPY"
    }
  ]
}

Request Parameters

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

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "price-limit",
    "instId": "BTC-JPY"
  },
  "connId": "a4d3ae55"
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"price-limit\", \"instId\" : \"BTC-JPY\"}]}",
  "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": "price-limit",
        "instId": "BTC-JPY"
    },
    "data": [{
        "instId": "BTC-JPY",
        "buyLmt": "200",
        "sellLmt": "300",
        "ts": "1597026383085",
        "enabled": true
    }]
}

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, e.g. `BTC-JPY`
> buyLmt	String	Maximum buy price Return "" when enabled is false
> sellLmt	String	Minimum sell price Return "" when enabled is false
> ts	String	Price update time, Unix timestamp format in milliseconds, e.g. `1597026383085`
> enabled	Boolean	Whether price limit is effective `true`: the price limit is effective `false`: the price limit is not effective

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 OKJ risk control and is temporarily restricted from conducting transactions. Please check your email registered with OKJ 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
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 OKJ 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 OKJ 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.
51024	200	Sub-accounts exceeding the limit aren't allowed to open new positions and can only reduce or close existing ones. Please try again with a different account.
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
51063	200	OrdId does not exist
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 OKJ 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	TP trigger prices (tpOrdPx) in one order with multiple TPs must be market prices.
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.
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	Insufficient conversion amount
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 JPY.
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.

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 JPY.
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}.
59329	200	Liability reduction failed. Repay this order instead.
51152	200	Holdings already reached the limit.
59402	200	No passed instIDs are in a live state. Please verify instIDs separately.
59410	200	You can only borrow this crypto if it supports borrowing and borrowing is enabled.
59411	200	Manual borrowing failed. Your account's free margin is insufficient.
59412	200	Manual borrowing failed. The amount exceeds your borrowing limit.
59413	200	You didn't borrow this crypto. No repayment needed.
59414	200	Manual borrowing failed. The minimum borrowing limit is {param0}.
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.

Trading bot

Error Code from 55100 to 55999

Error Code	HTTP Status Code	Error Message
55100	200	Take profit % should be within the range of {parameter1}-{parameter2}
55101	200	Stop loss % should be within the range of {parameter1}-{parameter2}
55102	200	Take profit % should be greater than the current bot’s PnL%
55103	200	Stop loss % should be less than the current bot’s PnL%
55104	200	Only futures grid supports take profit or stop loss based on profit percentage
55105	200	Increasing positions is not allowed under current status
55106	200	Increased amount should be within the range of {parameter1} - {parameter2}
55111	200	This signal name is in use, please try a new name
55112	200	This signal does not exist
55113	200	Create signal strategies with leverage greater than the maximum leverage of the instruments
55116	200	You can only place one chase order for each trading pair.

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.okj.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.okj.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.okj.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

Production Trading Services

General Info

Transaction Timeouts

REST API

WebSocket

Rate Limits

Trading-related APIs

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

Get all fee rates

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request