NAV
中文

Overview

Welcome to our V5 API documentation. OKX provides REST and WebSocket APIs to suit your trading needs.
The V5 API is only applicable to the Trading account.

API Resources and Support

V5 API Key Creation

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

Production Trading Services

The Production Trading URL:

AWS URL:

Demo Trading Services

Currently, the V5 API works for Demo Trading, but some functions are not supported, such as `withdraw','deposit','purchase/redemption', etc.

The Demo Trading URL:

OKX account can be used for login on Demo Trading. If you already have an OKX account, you can log in directly.

Start API Demo Trading by the following steps:
Login OKX —> Trade —> Demo Trading —> Personal Center —> Demo Trading API -> Create Demo Trading V5 API Key —> Start your Demo Trading

Http Header Example 

Content-Type: application/json

OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418

OK-ACCESS-SIGN: leaVRETrtaoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=

OK-ACCESS-PASSPHRASE: 1****6

OK-ACCESS-TIMESTAMP: 2020-03-28T12:21:41.274Z

x-simulated-trading: 1

General Info

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

The rules for the returning data are as follows:

The introduction of instFamily:

Transaction timeouts

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

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

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

REST

Set the following parameters in the request header

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

The following endpoints are supported:

Request Example

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

WebSocket

The following parameters are set in the request

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

The following endpoints are supported:

Request Example

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

Rate Limits

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

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

Best practices

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

Market Maker Program

High-caliber trading teams are welcomed to work with OKX as market makers in providing a liquid, fair, and orderly platform to all users. OKX market makers could enjoy favourable fees in return for meeting the market making obligations.

Prerequisites (Satisfy any condition):

Interested parties could drop us an email at [email protected] with the below details:

Remarks:

Market making obligations and trading fees will be shared to successful parties only.

Demo Trading Explorer

Get start

You need to sign in to your OKX account before accessing the explorer. The interface only allow access to the demo trading environment.

Try demo trading explorer

Block Trading

Block Trading Workflow

A block trade is a large sized, privately negotiated transaction that allows traders to execute spot, perpetuals, futures, options and a combination of instruments (multi leg) which are traded outside the order book and at a mutually agreed price between the counter-parties. Once the transaction economics have been agreed upon, it will be submitted to OKX to be seamlessly margined, cleared and executed.

Basic Concepts

  1. RFQs - Request for Quote sent by the Taker to Maker(s). It captures the quantity, instrument or multi instrument strategy that a Taker wants to trade.
  2. Quotes - Quotes are created by the Maker in response to a requested RFQ.
  3. Trades - Trades occur when the Taker successfully executes upon a makers quote to an RFQ.

High Level Workflow

To trade as either Taker or Maker, users need to deposit at least 100,000 USD into their trading account. In addition, to become a Maker, Please complete the form to access block trading.

  1. Taker creates an RFQ and selects which counterparties to broadcast the RFQ to.
  2. Multiple Maker(s) send a two way quote as a response to the RFQ.
  3. Taker chooses to execute upon the best quote and the trade is sent to OKX for clearing & settlement.
  4. Taker & Maker receive confirmation of the trade's execution.
  5. Trade economics are published to market feed. (minus counterparty info)

Taker's Perspective

  1. Taker creates an RFQ using POST /api/v5/rfq/create-rfq. Taker can pull available instruments via GET /api/v5/public/instruments and available counterparties from GET /api/v5/rfq/counterparties.
  2. Taker can cancel an RFQ anytime until it becomes inactive with POST /api/v5/rfq/cancel-rfq.
  3. Maker, who is a requested counterparty to the RFQ, and is notified over the rfqs WebSocket channel, can provide a Quote to the RFQ.
  4. Taker, who will be notified of quotes from the quotes WebSocket channel, can execute upon the best Quote with POST /api/v5/rfq/execute-quote.
  5. Taker will receive confirmation of the trade's successful execution on the struc-block-trades and rfqs WebSocket channel.
  6. Taker will also receive confirmation of the trade being completed on the public-struc-block-trades WebSocket channel as well as all other block trades on OKX.

Maker's Perspective

  1. Maker is notified about a new RFQ who they are a couterparty to, on the rfqs WebSocket channel.
  2. Maker can create a one way or two way Quote using POST /api/v5/rfq/create-quote.
  3. Maker can cancel an existing quote anytime until it becomes inactive with POST /api/v5/rfq/cancel-quote.
  4. Taker chooses to execute upon an available Quote.
  5. Maker will receive updates of their Quote from the quotes WebSocket channel.
  6. Maker will receive confirmation of the successful execution of their Quote from the struc-block-trades and quotes WebSocket channel.
  7. Maker will receive confirmation of the trade being completed on the public-struc-block-trades WebSocket channel as well as all other block trades on OKX.

REST API

Get Counterparties

Retrieves the list of counterparties that the user is permitted to trade with.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/rfq/counterparties

Request Example

GET /api/v5/rfq/counterparties

Request Parameters

None

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "traderName" : "Satoshi Nakamoto",
            "traderCode" : "SATOSHI",
            "type" : "" 
        }
    ]
}

Response Parameters

Parameters Types Description
traderName String The long formative username of trader or entity on the platform.
traderCode String A unique identifier of maker which will be publicly visible on the platform. All RFQ and Quote endpoints will use this as the unique counterparty identifier.
type String The counterparty type

Create RFQ

Creates a new RFQ

To learn more, please visit FAQ > Demo Trading

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/create-rfq

Request Example

POST /api/v5/rfq/create-rfq

{
    "anonymous": true,
    "counterparties":[
        "Trader1",
        "Trader2"
    ],
    "allowPartialExecution":false,
    "clRfqId":"rfq01",
    "tag":"123456",
    "legs":[
        {
            "sz":"25",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"BTCUSD-221208-100000-C"
        },
        {
            "sz":"150",
            "side":"buy",
            "posSide": "long",
            "tdMode":"cross",
            "ccy":"USDT",
            "instId":"ETH-USDT",
            "tgtCcy":"base_ccy"
        }
    ]
}

Request Parameters

Parameters Types Required Description
counterparties Array of strings Yes The trader code(s) of the counterparties who receive the RFQ. Can be found via /api/v5/rfq/counterparties/
anonymous Boolean No Submit RFQ on a disclosed or anonymous basis. Valid values are true or false. If not specified, the default value is false. When anonymous=true the taker’s identify is not disclosed to Maker even after trade execution.
clRfqId String No Client-supplied RFQ ID. A combination of case-sensitive alpha-numeric, all numbers, or all letters of up to 32 characters.
tag String No RFQ tag. The block trade associated with the RFQ will have the same tag.
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
allowPartialExecution Boolean No Whether the RFQ can be partially filled provided that the shape of legs stays the same. Valid values are true or false. false by default.
legs Array of objects Yes An Array of objects containing each leg of the RFQ. Maximum 15 legs can be placed per request
> instId String Yes The Instrument ID of each leg. Example : "BTC-USDT-SWAP"
> tdMode String No Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
> ccy String No Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
> sz String Yes The size of each leg
> side String Yes The direction of each leg. Valid values can be buy or sell.
> posSide String No Position side. The default is net in the net mode. It can only be long or short in the long/short mode.
If not specified, users in long/short mode always open new positions.
Only applicable to FUTURES/SWAP.
> tgtCcy String No Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified, this is equal to base_ccy by default.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "cTime":"1611033737572",
            "uTime":"1611033737572",
            "traderCode":"SATOSHI",
            "tag":"123456",
            "rfqId":"22534",
            "clRfqId":"rfq01",
            "allowPartialExecution":false,
            "state":"active",
            "validUntil":"1611033857557",
            "counterparties":[
                "Trader1",
                "Trader2"
            ],
            "legs":[
                {
                    "instId":"BTCUSD-221208-100000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"25",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "instId":"ETH-USDT",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"150",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":"base_ccy"     
                }
            ]
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results of the RFQ creation.
> cTime String The timestamp the RFQ was created. Unix timestamp format in milliseconds.
> uTime String The timestamp the RFQ was last updated. Unix timestamp format in milliseconds.
> state String The status of the RFQ.
Valid values can be active canceled pending_fill filled expired traded_away failed.
traded_away only applies to Maker
> counterparties Array of strings The list of counterparties traderCode the RFQ was broadcast to.
> validUntil String The timestamp the RFQ expires. Unix timestamp format in milliseconds.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> tag String RFQ tag. The block trade associated with the RFQ will have the same tag.
> allowPartialExecution Boolean Whether the RFQ can be partially filled provided that the shape of legs stays the same.
> traderCode String A unique identifier of taker.
> rfqId String The unique identifier of the RFQ generated by system.
> legs Array of objects An Array of objects containing each leg of the RFQ.
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String Size of the leg in contracts or spot.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Cancel RFQ

Cancel an existing active RFQ that you has previously created.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-rfq

Request Example

POST /api/v5/rfq/cancel-rfq
{
    "rfqId":"22535",
    "clRfqId":"rfq001"
}

Request Parameters

Parameters Types Required Description
rfqId String Conditional RFQ ID created .
clRfqId String Conditional Client-supplied RFQ ID. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
Either rfqId or clRfqId is required. If both are passed, rfqId will be used.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "rfqId":"22535",
            "clRfqId":"rfq001",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> rfqId String RFQ ID
> clRfqId String Client-supplied RFQ ID.
> sCode String The code of the event execution result, 0 means success.
> sMsg String Rejection message if the request is unsuccessful.

Cancel multiple RFQs

Cancel one or multiple active RFQ(s) in a single batch. Maximum 100 RFQ orders can be canceled per request.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-batch-rfqs

Request Example

POST /api/v5/rfq/cancel-batch-rfqs
{
    "rfqIds":[
        "2201",
        "2202",
        "2203"
    ],
    "clRfqIds":[
        "r1",
        "r2",
        "r3"
    ]
}

Request Parameters

Parameters Types Required Description
rfqIds Array of strings Conditional RFQ IDs .
clRfqIds Array of strings Conditional Client-supplied RFQ IDs. Either rfqIds or clRfqIds is required.If both attributes are sent, rfqIds will be used as primary identifier.

Success - All requested RFQs canceled 

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Partial cancelation 

{
    "code":"2",
    "msg":"Bulk operation partially ",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Failure example

{
    "code":"1",
    "msg":"Operation failed.",
    "data":[
        {
            "rfqId":"2201",
            "clRfqId":"r1",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2202",
            "clRfqId":"r2",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        },
        {
            "rfqId":"2203",
            "clRfqId":"r3",
            "sCode":"70000",
            "sMsg":"RFQ does not exist."
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> rfqId String RFQ ID
> clRfqId String Client-supplied RFQ ID.
> sCode String The code of the event execution result, 0 means success.
> sMsg String Rejection message if the request is unsuccessful.

Cancel all RFQs

Cancels all active RFQs.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-all-rfqs

Request Example

POST /api/v5/rfq/cancel-all-rfqs

Request Parameters

None

Response Example

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

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> ts String The timestamp of successful cancelation. Unix timestamp format in milliseconds, e.g. 1597026383085.

Execute Quote

Executes a Quote. It is only used by the creator of the RFQ

Rate Limit: 2 requests per 3 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/execute-quote

Request Example

POST /api/v5/rfq/execute-quote
{
    "rfqId":"22540",
    "quoteId":"84073",
    "legs":[
        {
            "sz":"25",
            "instId":"BTC-USD-20220114-13250-C"
        },
        {
            "sz":"25",
            "instId":"BTC-USDT"
        }
     ]
}

Request Parameters

Parameters Types Required Description
rfqId String Yes RFQ ID .
quoteId String Yes Quote ID.
legs Array of objects No An Array of objects containing the execution size of each leg of the RFQ. The ratio of the leg sizes needs to be the same as the RFQ. *Note: tgtCcy and side of each leg will be same as ones in the RFQ. px will be the same as the ones in the Quote.
> instId String Yes The Instrument ID, for example: "BTC-USDT-SWAP".
> sz String Yes The size of each leg

Response Example

{  
   "code":"0",
   "msg":"",
   "data":[
       {
            "blockTdId":"180184",
            "rfqId":"1419",
            "clRfqId":"r0001",
            "quoteId":"1046",
            "clQuoteId":"q0001",
            "tag":"123456",
            "tTraderCode":"Trader1",
            "mTraderCode":"Trader2",
            "cTime":"1649670009",
            "legs":[
                {
                    "px":"0.1",
                    "sz":"25",
                    "instId":"BTC-USD-20220114-13250-C",
                    "side":"sell",
                    "fee":"-1.001",
                    "feeCcy":"BTC",
                    "tradeId":"10211"
                },
                {
                    "px":"0.2",
                    "sz":"25",
                    "instId":"BTC-USDT",
                    "side":"buy",
                    "fee":"-1.001",
                    "feeCcy":"BTC",
                    "tradeId":"10212"
                }
            ]
        }
   ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> cTime String The execution time for the trade. Unix timestamp in milliseconds.
> rfqId String RFQ ID.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> quoteId String Quote ID.
> clQuoteId String Client-supplied Quote ID. This attribute is treated as client sensitive information. It will not be exposed to the Taker, only return empty string.
> blockTdId String Block trade ID.
> tag String Trade tag. The block trade will have the tag of the RFQ or Quote it corresponds to.
> tTraderCode String A unique identifier of the taker. Empty if the anonymous parameter of the RFQ is set to be true.
> mTraderCode String A unique identifier of the maker. Empty if the anonymous parameter of the Quote is set to be true.
> legs Array of objects Legs of trade
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> px String The price the leg executed
>> sz String Size of the leg in contracts or spot.
>> side String The direction of the leg from the Takers perspective. Valid value can be buy or sell.
>> fee String Fee for the individual leg. Negative fee represents the user transaction fee charged by the platform. Positive fee represents rebate.
>> feeCcy String Fee currency. To be read in conjunction with fee
>> tradeId String Last traded ID.

Get Quote products

Retrieve the products which makers want to quote and receive RFQs for, and the corresponding price and size limit.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/rfq/maker-instrument-settings

Request Example

GET /api/v5/rfq/maker-instrument-settings

Request Parameters

None

Response Example

{
    "code": "0",
    "msg": "",
    "data":
        [
            {"instType": "OPTION",
             "includeALL": true,
             "data":
                [
                {    
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                    },
                {
                    "uly": "SOL-USD",
                    "maxBlockSz": "100000",
                    "makerPxBand": "15"
                    }
                ]
            },
            {"instType": "FUTURES",
             "includeALL": false,
             "data":
                [
                {
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                },
                {
                    "uly": "ETH-USDT",
                    "maxBlockSz": "100000",
                    "makerPxBand": "15"
                }
                ]
            },
            {"instType:": "SWAP",
             "includeALL": false,
             "data":
                [{
                    "uly": "BTC-USD",
                    "maxBlockSz": "10000",
                    "makerPxBand": "5"
                    },
                {
                    "uly": "ETH-USDT"
                    }
                ]
            },
                {"instType:": "SPOT",
                 "includeALL": false,
                 "data":
                    [{
                        "instId": "BTC-USDT"
                        },
                    {
                        "instId": "TRX-USDT"
                        }
                    ]

        ]
    }

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Return data of the request.
> instType String Type of instrument. Valid value can be FUTURES, OPTION, SWAP or SPOT.
> includeAll Boolean Receive all instruments or not under specific instType setting. Valid value can be boolean (True/False). By default, the value will be false.
> data Array of objects Elements of the instType.
>> instFamily String Instrument family. Required for FUTURES, OPTION and SWAP only.
>> instId String Instrument ID. Required for SPOT only.
>> maxBlockSz String Max trade quantity for the product(s).
For FUTURES, OPTION and SWAP, the max quantity of the RFQ/Quote is in unit of contracts. For SPOT, this parameter is in base currency.
>> makerPxBand String Price bands in unit of ticks, measured against mark price.
Setting makerPxBand to 1 tick means:
If Bid price > Mark + 1 tick, it will be stopped
If Ask price < Mark - 1 tick, It will be stopped

Set Quote products

Customize the products which makers want to quote and receive RFQs for, and the corresponding price and size limit.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/maker-instrument-settings

Request Example

POST /api/v5/rfq/maker-instrument-settings
[
    {
     "instType": "OPTION",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
        },
        {
            "instFamily": "SOL-USD",
            "maxBlockSz": "100000",
            "makerPxBand": "15"
        }]
    },
    {
     "instType": "FUTURES",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
        },
        {
            "instFamily": "ETH-USDT",
            "maxBlockSz": "100000",
            "makerPxBand": "15"
        }]
    },
    {
     "instType": "SWAP",
     "data":
        [{
            "instFamily": "BTC-USD",
            "maxBlockSz": "10000",
            "makerPxBand": "5"
         },
        {
            "instFamily": "ETH-USDT"
        }]
    },
    {
    "instType": "SPOT",
     "data":
        [{
            "instId": "BTC-USDT"
         },
        {
            "instId": "TRX-USDT"
        }]
    }
]

Request Parameters

Parameters Types Required Description
instType String Yes Type of instrument. Valid value can be FUTURES, OPTION, SWAP or SPOT.
includeAll Boolean No Receive all instruments or not under specific instType setting. Valid value can be boolean (True/False). By default, the value will be false.
data Array of objects Yes Elements of the instType.
> instFamily String Conditional Instrument family. Required for FUTURES, OPTION and SWAP only.
> instId String Conditional Instrument ID. Required for SPOT only.
> maxBlockSz String No Max trade quantity for the product(s).
For FUTURES, OPTION and SWAP, the max quantity of the RFQ/Quote is in unit of contracts. For SPOT, this parameter is in base currency.
> makerPxBand String No Price bands in unit of ticks, measured against mark price.
Setting makerPxBand to 1 tick means:
If Bid price > Mark + 1 tick, it will be stopped
If Ask price < Mark - 1 tick, It will be stopped

Response Example

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

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results.
> result Boolean Result of the request
Valid value is true or false.

Reset MMP status

Reset the MMP status to be inactive.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/mmp-reset

Request Example

POST /api/v5/rfq/mmp-reset

Request Parameters

None

Response Example

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

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results.
ts String The timestamp of re-setting successfully. Unix timestamp format in milliseconds, e.g. 1597026383085.

Create Quote

Allows the user to Quote an RFQ that they are a counterparty to. The user MUST quote the entire RFQ and not part of the legs or part of the quantity. Partial quoting or partial fills are not allowed.

Rate Limit: 50 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/create-quote

Request Example

POST /api/v5/rfq/create-quote
{
    "rfqId":"22539",
    "clQuoteId":"q001",
    "tag":"123456",
    "quoteSide":"buy",
    "anonymous": true,
    "expiresIn":"30",
    "legs":[
        {
            "px":"39450.0",
            "sz":"200000",
            "instId":"BTC-USDT-SWAP",
            "tdMode":"cross",
            "ccy":"USDT",
            "side":"buy",
            "posSide": "long"
        },
        {
            "px":"39450.0",
            "sz":"200000",
            "instId":"BTC-USDT-SWAP",
            "tdMode":"cross",
            "ccy":"USDT",
            "side":"buy",
            "posSide": "long"
        }
    ]
}

Request Parameters

Parameters Types Required Description
rfqId String Yes RFQ ID .
clQuoteId String No Client-supplied Quote ID. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag String No Quote tag. The block trade associated with the Quote will have the same tag.
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
anonymous Boolean No Submit Quote on a disclosed or anonymous basis.Valid value is true or false. false by default.
quoteSide String Yes The trading direction of the Quote. Its value can be buy or sell. For example, if quoteSide is buy, all the legs are executed in their leg sides; otherwise, all the legs are executed in the opposite of their leg sides.
expiresIn String No Seconds that a quote expires in. Must be an integer between 10-120. Default is 60.
legs Array of objects Yes The legs of the Quote.
> instId String Yes The instrument ID of quoted leg.
> tdMode String No Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
> ccy String No Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
> sz String Yes Size of the leg in contracts or spot.
> px String Yes The price of the leg.
> side String Yes The direction of the leg. Valid values can be buy or sell.
> posSide String No Position side. The default is net in the net mode. It can only be long or short in the long/short mode.
If not specified, users in long/short mode always open new positions.
Only applicable to FUTURES/SWAP.
> tgtCcy String No Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Response Example

{
    "code":"",
    "msg":"",
    "data":[
        {
            "validUntil":"1608997227834",
            "uTime":"1608267227834",
            "cTime":"1608267227834",
            "legs":[
                {
                    "px":"46000",
                    "sz":"25",
                    "instId":"BTC-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "px":"4000",
                    "sz":"25",
                    "instId":"ETH-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""
                }
            ],
            "quoteId":"25092",
            "rfqId":"18753",
            "tag":"123456",
            "quoteSide":"sell",
            "state":"active",
            "reason": "mmp_canceled"
            "clQuoteId":"",
            "clRfqId":"",
            "traderCode":"Aksha"
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> cTime String The timestamp the Quote was created, Unix timestamp format in milliseconds.
> uTime String The timestamp the Quote was last updated, Unix timestamp format in milliseconds.
> state String The status of the quote. Valid values can be active canceled pending_fill filled expired or failed.
> reason String Reasons of state. Valid values can be mmp_canceled.
> validUntil String The timestamp the Quote expires. Unix timestamp format in milliseconds.
> rfqId String RFQ ID
> clRfqId String Client-supplied RFQ ID.This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> quoteId String Quote ID.
> clQuoteId String Client-supplied Quote ID.This attribute is treated as client sensitive information. It will not be exposed to the Taker, only return empty string.
> tag String Quote tag. The block trade associated with the Quote will have the same tag.
> traderCode String A unique identifier of maker.
> quoteSide String The trading direction of the Quote. Its value can be buy or sell. For example, if quoteSide is buy, all the legs are executed in their leg sides; otherwise, all the legs are executed in the opposite of their leg sides.
> legs Array of objects Size of the leg in contracts or spot.
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String Size of the leg in contracts or spot.
>> px String The price of the leg.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Cancel Quote

Cancels an existing active Quote you have created in response to an RFQ.

Rate Limit: 50 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-quote

Request Example

POST /api/v5/rfq/cancel-quote
{
    "quoteId": "007",
    "clQuoteId":"Bond007"
}

Request Parameters

Parameters Types Required Description
quoteId String Conditional Quote ID.
clQuoteId String Conditional Client-supplied Quote ID. Either quoteId or clQuoteId is required. If both clQuoteId and quoteId are passed, quoteId will be treated as primary identifier.
rfqId String No RFQ ID.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "quoteId":"007",
            "clQuoteId":"Bond007",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> quoteId String Quote ID
> clQuoteId String Client-supplied Quote ID.
> sCode String The code of the event execution result, 0 means success.
> sMsg String Rejection message if the request is unsuccessful.

Cancel multiple Quotes

Cancel one or multiple active Quote(s) in a single batch. Maximum 100 quote orders can be canceled per request.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-batch-quotes

Request Example

POST /api/v5/rfq/cancel-batch-quotes
{
    "quoteIds":["1150","1151","1152"],
    "clQuoteIds":["q1","q2","q3"]
}

Request Parameters

Parameters Types Required Description
quoteIds Array of strings Conditional Quote IDs .
clQuoteIds Array of strings Conditional Client-supplied Quote IDs. Either quoteIds or clQuoteIds is required.If both attributes are sent, quoteIds will be used as primary identifier.

Success - All requested Quotes canceled 

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1152",
            "clQuoteId":"q3",
            "sCode":"0",
            "sMsg":""
        }
    ]
}

Partial cancelation 

{
    "code":"2",
    "msg":"Bulk operation partially succeeded.",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"0",
            "sMsg":""
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1152",
            "clQuoteId":"q3",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        }
    ]
}

Failure example

{
    "code":"1",
    "msg":"Operation failed.",
    "data":[
        {
            "quoteId":"1150",
            "clQuoteId":"q1",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q2",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        },
        {
            "quoteId":"1151",
            "clQuoteId":"q3",
            "sCode":"70001",
            "sMsg":"Quote does not exist."
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> quoteId String Quote ID
> clQuoteId String Client-supplied Quote ID.
> sCode String The code of the event execution result, 0 means success.
> sMsg String Rejection message if the request is unsuccessful.

Cancel all Quotes

Cancels all active Quotes.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

POST /api/v5/rfq/cancel-all-quotes

Request Example

POST /api/v5/rfq/cancel-all-quotes

Request Parameters

None

Response Example

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

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results
> ts String The timestamp of cancellation successfully. Unix timestamp format in milliseconds, e.g. 1597026383085.

Get rfqs

Retrieves details of RFQs that the user is a counterparty to (either as the creator or the receiver of the RFQ).

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/rfq/rfqs

Request Example

GET /api/v5/rfq/rfqs

Request Parameters

Parameters Types Required Description
rfqId String No RFQ ID .
clRfqId String No Client-supplied RFQ ID. If both clRfqId and rfqId are passed, rfqId will be treated as primary identifier
state String No The status of the RFQ.
Valid values can be active canceled pending_fill filled expired failed traded_away.
traded_away only applies to Maker
beginId String No Start rfq id the request to begin with. Pagination of data to return records newer than the requested rfqId, not including beginId
endId String No End rfq id the request to end with. Pagination of data to return records earlier than the requested rfqId, not including endId
limit String No Number of results per request. The maximum is 100 which is also the default value.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "rfqId": "123456",
            "clRfqId": "",
            "tag": "123456",
            "traderCode": "VITALIK",
            "validUntil": "1650969031817",
            "allowPartialExecution": false,
            "state": "filled",
            "counterparties": [
                "SATOSHI"
            ],
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side": "buy",
                    "posSide": "long",
                    "sz": "25",
                    "tgtCcy": "base_ccy"
                }
            ],
            "cTime": "1650968131817",
            "uTime": "1650968164944"
        },
        {
            "rfqId": "1234567",
            "clRfqId": "",
            "tag":"1234567",
            "traderCode": "VITALIK",
            "validUntil": "1650967623729",
            "state": "filled",
            "counterparties": [
                "SATOSHI"
            ],
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side": "buy",
                    "posSide": "long",
                    "sz": "1500000",
                    "tgtCcy": "quote_ccy"
                }
            ],
            "cTime": "1650966723729",
            "uTime": "1650966816577"
        }
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results of the RFQ creation.
> cTime String The timestamp the RFQ was created. Unix timestamp format in milliseconds.
> uTime String The timestamp the RFQ was last updated. Unix timestamp format in milliseconds.
> state String The status of the RFQ.
Valid values can be active canceled pending_fill filled expired failed traded_away.
traded_away only applies to Maker
> counterparties Array of srings The list of counterparties traderCode the RFQ was broadcasted to.
> validUntil String The timestamp the RFQ expires. Unix timestamp format in milliseconds.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> tag String RFQ tag. The block trade associated with the RFQ will have the same tag.
> traderCode String A unique identifier of taker. Empty if the anonymous parameter of the RFQ is set to be true.
> rfqId String RFQ ID.
> allowPartialExecution Boolean Whether the RFQ can be partially filled provided that the shape of legs stays the same.
Valid value is true or false. false by default.
> legs Array of objects Legs of RFQ
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String Size of the leg in contracts or spot.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Get quotes

Retrieve all Quotes that the user is a counterparty to (either as the creator or the receiver).

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/rfq/quotes

Request Example

GET /api/v5/rfq/quotes

Request Parameters

Parameters Types Required Description
rfqId String No RFQ ID .
clRfqId String No Client-supplied RFQ ID. If both clRfqId and rfqId are passed, rfqId will be be treated as primary identifier.
quoteId String No Quote ID
clQuoteId String No Client-supplied Quote ID. If both clQuoteId and quoteId are passed, quoteId will be treated as primary identifier
state String No The status of the quote. Valid values can be active canceled pending_fill filled expired or failed.
beginId String No Start quote id the request to begin with. Pagination of data to return records newer than the requested quoteId, not including beginId
endId String No End quote id the request to end with. Pagination of data to return records earlier than the requested quoteId, not including endId
limit String No Number of results per request. The maximum is 100 which is also the default value.

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "validUntil":"1608997227834",
            "uTime":"1608267227834",
            "cTime":"1608267227834",
            "legs":[
                {
                    "px":"46000",
                    "sz":"25",
                    "instId":"BTC-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "px":"45000",
                    "sz":"25",
                    "instId":"BTC-USDT",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":"base_ccy"
                }
            ],
            "quoteId":"25092",
            "rfqId":"18753",
            "quoteSide":"sell",
            "state":"canceled",
            "reason":"mmp_canceled",
            "clQuoteId":"cq001",
            "clRfqId":"cr001",
            "tag":"123456",
            "traderCode":"Trader1"
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results of the Quote creation.
> cTime String The timestamp the Quote was created, Unix timestamp format in milliseconds.
> uTime String The timestamp the Quote was last updated, Unix timestamp format in milliseconds.
> state String The status of the quote. Valid values can be active canceled pending_fill filled expired or failed.
> reason String Reasons of state. Valid values can be mmp_canceled.
> validUntil String The timestamp the Quote expires. Unix timestamp format in milliseconds.
> rfqId String RFQ ID.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> quoteId String Quote ID.
> clQuoteId String Client-supplied Quote ID. This attribute is treated as client sensitive information. It will not be exposed to the Taker, only return empty string.
> tag String Quote tag. The block trade associated with the Quote will have the same tag.
> traderCode String A unique identifier of maker. Empty If the anonymous parameter of the Quote is set to be true.
> quoteSide String Top level direction of Quote. Its value can be buy or sell.
> legs Array of objects The legs of the Quote.
>> instId String The instrument ID of the quoted leg.
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String Size of the leg in contracts or spot.
>> px String The price of the leg.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Get trades

Retrieves the executed trades that the user is a counterparty to (either as the creator or the receiver).

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/rfq/trades

Request Example

GET /api/v5/rfq/trades

Request Parameters

Parameters Types Required Description
rfqId String No RFQ ID .
clRfqId String No Client-supplied RFQ ID. If both clRfqId and rfqId are passed, rfqId will be treated as primary identifier
quoteId String No Quote ID
blockTdId String No Block trade ID
clQuoteId String No Client-supplied Quote ID. If both clQuoteId and quoteId are passed, quoteId will be treated as primary identifier
state String No The status of the RFQ.
Valid values can be active canceled pending_fill filled expired failed traded_away.
traded_away only applies to Maker
beginId String No The starting rfq id the request to begin with. Pagination of data to return records newer than the requested blockTdId, not including beginId.
endId String No The last rfq id the request to end withPagination of data to return records earlier than the requested blockTdId, not including endId.
beginTs String No Filter trade execution time with a begin timestamp (UTC timezone). Unix timestamp format in milliseconds, e.g. 1597026383085
endTs String No Filter trade execution time with an end timestamp (UTC timezone). Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100 which is also the default value.
If the number of trades in the requested range is bigger than 100, the latest 100 trades in the range will be returned.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "rfqId": "123456",
            "clRfqId": "",
            "quoteId": "0T5342O",
            "clQuoteId": "",
            "blockTdId": "439127542058958848",
            "tag": "123456",
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "side": "sell",
                    "sz": "0.666",
                    "px": "100",
                    "tradeId": "439127542058958850",
                    "fee": "-0.0333",
                    "feeCcy": "USDT"
                }
            ],
            "cTime": "1650968164900",
            "tTraderCode": "SATS",
            "mTraderCode": "MIKE"
        },
        {
            "rfqId": "1234567",
            "clRfqId": "",
            "quoteId": "0T533T0",
            "clQuoteId": "",
            "blockTdId": "439121886014849024",
            "tag": "1234567",
            "legs": [
                {
                    "instId": "BTC-USDT",
                    "side": "sell",
                    "sz": "0.532",
                    "px": "100",
                    "tradeId": "439121886014849026",
                    "fee": "-0.0266",
                    "feeCcy": "USDT"
                }
            ],
            "cTime": "1650966816550",
            "tTraderCode": "SATS",
            "mTraderCode": "MIKE"
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results of the block trade.
> cTime String The time the trade was executed. Unix timestamp in milliseconds.
> rfqId String RFQ ID.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, only return empty string.
> quoteId String Quote ID.
> clQuoteId String Client-supplied Quote ID. This attribute is treated as client sensitive information. It will not be exposed to the Taker, only return empty string.
> blockTdId String Block trade ID.
> tag String Trade tag. The block trade will have the tag of the RFQ or Quote it corresponds to.
> tTraderCode String A unique identifier of the Taker. Empty if the anonymous parameter of the RFQ is set to be true.
> mTraderCode String A unique identifier of the Maker. Empty if the anonymous parameter of the Quote is set to be true.
> legs Array of objects Legs of trade
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> px String The price the leg executed
>> sz String Size of the leg in contracts or spot.
>> side String The direction of the leg. Valid value can be buy or sell.
>> fee String Fee.Negative number represents the user transaction fee charged by the platform.Positive number represents rebate.
>> feeCcy String Fee currency
>> tradeId String Last traded ID.

Get public trades

Retrieves the recent executed block trades.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Requests

GET /api/v5/rfq/public-trades

Request Example

GET /api/v5/rfq/public-trades

Request Parameters

Parameters Types Required Description
beginId String No The starting rfq id the request to begin with. Pagination of data to return records newer than the requested blockTdId, not including beginId.
endId String No The last rfq id the request to end with. Pagination of data to return records earlier than the requested blockTdId, not including endId.
limit String No Number of results per request. The maximum is 100 which is also the default value.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "blockTdId": "439161457415012352",
            "legs": [
                {
                    "instId": "BTC-USD-210826",
                    "side": "sell",
                    "sz": "100",
                    "px": "11000",
                    "tradeId": "439161457415012354"
                },
                {
                    "instId": "BTC-USD-SWAP",
                    "side": "sell",
                    "sz": "100",
                    "px": "50",
                    "tradeId": "439161457415012355"
                },
                {
                    "instId": "BTC-USDT",
                    "side": "buy",
                    "sz": "0.1", //for public feed, spot "sz" is in baseccy
                    "px": "10.1",
                    "tradeId": "439161457415012356"
                },
                {
                    "instId": "BTC-USD-210326-60000-C",
                    "side": "buy",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012357"
                },
                {
                    "instId": "BTC-USD-220930-5000-P",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012360"
                },
                {
                    "instId": "BTC-USD-220930-10000-C",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012361"
                },
                {
                    "instId": "BTC-USD-220930-10000-P",
                    "side": "sell",
                    "sz": "200",
                    "px": "0.008",
                    "tradeId": "439161457415012362"
                },
                {
                    "instId": "ETH-USD-220624-100100-C",
                    "side": "sell",
                    "sz": "100",
                    "px": "0.008",
                    "tradeId": "439161457415012363"
                }
            ],
            "cTime": "1650976251241"
        }
    ]
}

Response Parameters

Parameters Types Description
code String The result code, 0 means success.
msg String The error message, not empty if the code is not 0.
data Array of objects Array of objects containing the results of the public block trade.
> cTime String The time the trade was executed. Unix timestamp in milliseconds.
> blockTdId String Block trade ID.
> legs Array of objects Legs of trade
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> px String The price the leg executed
>> sz String Size of the leg in contracts or spot.
>> side String The direction of the leg from the Takers perspective. Valid value can be buy or sell.
>> tradeId String Last traded ID.

WebSocket Private Channel

Rfqs channel

Retrieve the RFQs sent or received by the user. Data will be pushed whenever the user sends or receives an RFQ.

Request Example

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

Request parameters

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

Successful Response Example 

{
  "event": "subscribe",
  "arg": {
    "channel": "rfqs"
  }
}

Failure Response Example

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

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, rfqs
code String No Error code
msg String No Error message

Push Data Example

{
    "arg":{
        "channel":"rfqs",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "cTime":"1611033737572",
            "uTime":"1611033737572",
            "traderCode":"DSK2",
            "rfqId":"22534",
            "clRfqId":"",
            "tag":"123456",
            "state":"active",
            "validUntil":"1611033857557",
            "allowPartialExecution": false,
            "counterparties":[
                "DSK4",
                "DSK5"
            ],
            "legs":[
                {
                    "instId":"BTCUSD-211208-36000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"25.0",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""
                },
                {
                    "instId":"ETHUSD-211208-45000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "sz":"25.0",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""
                }
            ]
        }
    ]
}

Push data parameters

Parameters Types Description
arg Object Successfully subscribed channel
> channel String Channel name
> uid String User Identifier
data Array Subscribed data
> cTime String The timestamp the RFQ was created, Unix timestamp format in milliseconds.
> uTime String The timestamp the RFQ was updated latest, Unix timestamp format in milliseconds.
> state String The status of the RFQ. Valid values can be active, canceled, filled, expired or failed.
> counterparties Array of Strings The list of counterparties traderCode the RFQ was broadcasted to.
> validUntil String The timestamp the RFQ expires. Unix timestamp format in milliseconds.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker. Return empty for Maker. eg. ""
> tag String RFQ tag. The block trade associated with the RFQ will have the same tag.
> traderCode String A unique identifier of taker. Empty If anonymous mode is True.
> rfqId String RFQ ID
> allowPartialExecution Boolean Whether the RFQ can be partially filled provided that the shape of legs stays the same.
Valid value is true or false.
false by default.
> legs Array of objects An Array of objects containing each leg of the RFQ.
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String Size of the leg.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Quotes channel

Retrieve the Quotes sent or received by the user. Data will be pushed whenever the user sends or receives a Quote.

Request Example

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

Request parameters

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

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "quotes"
  }
}

Failure Response Example

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

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, quotes
code String No Error code
msg String No Error message

Push Data Example

{
    "arg":{
        "channel":"quotes",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "validUntil":"1608997227854",
            "uTime":"1608267227834",
            "cTime":"1608267227834",
            "legs":[
                {
                    "px":"0.0023",
                    "sz":"25.0",
                    "instId":"BTC-USD-220114-25000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"sell",
                    "posSide": "long",
                    "tgtCcy":""

                },
                {
                    "px":"0.0045",
                    "sz":"25",
                    "instId":"BTC-USD-220114-35000-C",
                    "tdMode":"cross",
                    "ccy":"USDT",
                    "side":"buy",
                    "posSide": "long",
                    "tgtCcy":""

                }
            ],
            "quoteId":"25092",
            "rfqId":"18753",
            "tag":"123456",
            "traderCode":"SATS",
            "quoteSide":"sell",
            "state":"canceled",
            "reason":"mmp_canceled",
            "clQuoteId":""
        }
    ]
}

Push data parameters

Parameters Types Description
arg Object Successfully subscribed channel
> channel String Channel name
> uid String User Identifier
data Array Subscribed data
> cTime String The timestamp the Quote was created, Unix timestamp format in milliseconds.
> uTime String The timestamp the Quote was updated latest, Unix timestamp format in milliseconds.
> state String The status of the quote. Valid values can be active canceled filled expired or failed.
> reason String Reasons of state. Valid values can be mmp_canceled.
> validUntil String The timestamp the Quote expires. Unix timestamp format in milliseconds.
> rfqId String RFQ ID.
> clRfqId String Client-supplied RFQ ID.This attribute is treated as client sensitive information. It will not be exposed to the Maker, just return empty string "" for Maker.
> quoteId String Quote ID
> clQuoteId String Client-supplied Quote ID.This attribute is treated as client sensitive information. It will not be exposed to the Taker, just return empty string "" for Taker.
> tag String Quote tag. The block trade associated with the Quote will have the same tag.
> traderCode String A unique identifier of maker. Empty If anonymous mode of Quote is True.
> quoteSide String Top level side of Quote. Its value can be buy or sell.
> legs Array of objects The legs of the Quote.
>> instId String The instrument name of quoted leg.
>> tdMode String Trade mode
Margin mode: cross isolated
Non-Margin mode: cash.
If not provided, tdMode will inherit default values set by the system shown below:
Single-currency margin mode & SPOT: cash
Buy options in Single-currency margin and Multi-currency Margin: isolated
Other cases: cross
>> ccy String Margin currency.
Only applicable to cross MARGIN orders in Single-currency margin. The parameter will be ignored in other scenarios.
>> sz String The size of the quoted leg in contracts or spot.
>> px String The price of the leg.
>> side String The direction of the leg. Valid values can be buy or sell.
>> posSide String Position side. The default is net in the net mode. If not specified, return "", which is equivalent to net.
It can only be long or short in the long/short mode. If not specified, return "", which corresponds to the direction that opens new positions for the trade (buy => long, sell => short).
Only applicable to FUTURES/SWAP.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.

Structure block trades channel

Retrieve user's block trades data. All the legs in the same block trade are included in the same update. Data will be pushed whenever there is a block trade that the user is a counterparty for.

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "struc-block-trades"
    }
  ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, struc-block-trades

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "struc-block-trades"
  }
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"struc-block-trades\""}]}"
}

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, struc-block-trades
code String No Error code
msg String No Error message

Push Data Example

{
    "arg":{
        "channel":"struc-block-trades",
        "uid": "77982378738415879"
    },
    "data":[
        {
            "cTime":"1608267227834",
            "rfqId":"18753",
            "clRfqId":"",
            "quoteId":"25092",
            "clQuoteId":"",
            "blockTdId":"180184",
            "tag":"123456",
            "tTraderCode":"ANAND",
            "mTraderCode":"WAGMI",
            "legs":[
                {
                    "px":"0.0023",
                    "sz":"25.0",
                    "instId":"BTC-USD-20220630-60000-C",
                    "side":"sell",
                    "fee":"0.1001",
                    "feeCcy":"BTC",
                    "tradeId":"10211",
                    "tgtCcy":""

                },
                {
                    "px":"0.0033",
                    "sz":"25",
                    "instId":"BTC-USD-20220630-50000-C",
                    "side":"buy",
                    "fee":"0.1001",
                    "feeCcy":"BTC",
                    "tradeId":"10212",
                    "tgtCcy":""

                }
            ]
        }
    ]
}

Push data parameters

Parameters Types Description
arg Object Successfully subscribed channel
> channel String Channel name
> uid String User Identifier
data Array Subscribed data
> cTime String The time the trade was executed. Unix timestamp in milliseconds.
> rfqId String RFQ ID.
> clRfqId String Client-supplied RFQ ID. This attribute is treated as client sensitive information. It will not be exposed to the Maker, just return empty string "" for Maker.
> quoteId String Quote ID.
> clQuoteId String Client-supplied Quote ID. This attribute is treated as client sensitive information. It will not be exposed to the Taker, just return empty string "" for Taker.
> blockTdId String Block trade ID.
> tag String Trade tag. The block trade will have the tag of the RFQ or Quote it corresponds to.
> tTraderCode String A unique identifier of the Taker. Empty If anonymous mode of RFQ is True.
> mTraderCode String A unique identifier of the Maker. Empty If anonymous mode of Quote is True.
> legs Array of objects Legs of trade
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> px String The price the leg executed
>> sz String Size of the leg.
>> side String The direction of the leg. Valid value can be buy or sell.
>> tgtCcy String Defines the unit of the “sz” attribute. Only applicable to instType = SPOT. The valid enumerations are base_ccy and quote_ccy. When not specified this is equal to base_ccy by default.
>> fee String Fee. Negative number represents the user transaction fee charged by the platform. Positive fee represents rebate.
>> feeCcy String Fee currency
>> tradeId String Last traded ID.

WebSocket Public Channel

Public structure block trades channel

Retrieve the recent block trades data in OKX. All the legs in the same block trade are included in the same update. Data will be pushed whenever there is a block trade in OKX.

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "public-struc-block-trades"
    }
  ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, public-struc-block-trades

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "public-struc-block-trades"
  }
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"public-struc-block-trades\""}]}"
}

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, public-struc-block-trades
code String No Error code
msg String No Error message

Push Data Example

{
    "arg":{
        "channel":"public-struc-block-trades"
    },
    "data":[
        {

            "cTime":"1608267227834",
            "blockTdId":"1802896",
            "legs":[
                {
                    "px":"0.323",
                    "sz":"25.0",
                    "instId":"BTC-USD-20220114-13250-C",
                    "side":"sell",
                    "tradeId":"15102"
                },
                {
                    "px":"0.666",
                    "sz":"25",
                    "instId":"BTC-USD-20220114-21125-C",
                    "side":"buy",
                    "tradeId":"15103"
                }
            ]
        }
    ]
}

Push data parameters

Parameters Types Description
arg Object Successfully subscribed channel
> channel String Channel name
data Array Subscribed data
> cTime String The time the trade was executed. Unix timestamp in milliseconds.
> blockTdId String Block trade ID.
> legs Array of objects Legs of trade
>> instId String Instrument ID, e.g., BTC-USDT-SWAP
>> px String The price the leg executed
>> sz String Size of the leg.
>> side String The direction of the leg from the Takers perspective. Valid value can be buy or sell.
>> tradeId String Last traded ID.

Public block trades channel

Retrieve the recent block trades data by individual legs. Each leg in a block trade is pushed in a separate update. Data will be pushed whenever there is a block trade.

Request Example

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

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, public-block-trades
> instId String Yes Instrument ID, e.g., BTC-USDT-SWAP.

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "public-block-trades",
    "instId": "BTC-USDT-SWAP"
  }
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Invalid request: {\"op\": \"subscribe\", \"args\":[{ \"channel\" : \"public-block-trades\""}]}"
}

Response parameters

Parameter Type Required Description
event String Yes Operation, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, public-block-trades
> instId String Yes Instrument ID, e.g., BTC-USDT-SWAP.
code String No Error code
msg String No Error message

Push Data Example

{
  "arg": {
    "channel": "public-block-trades",
    "instId": "BTC-USDT-SWAP"
  },
  "data": [
    {
      "instId": "BTC-USDT-SWAP",
      "tradeId": "482866817984270338",
      "px": "21950",
      "sz": "100",
      "side": "buy",
      "ts": "1661396420687"
    }
  ]
}

Push data parameters

Parameters Types Description
arg Object Successfully subscribed channel
> channel String Channel name
> instId String Instrument ID, e.g., BTC-USDT-SWAP.
data Array Information of the public trade object.
> instId String Instrument ID, e.g., BTC-USDT-SWAP.
> tradeId String Trade ID, generated by counter.
> px String The price the leg executed.
> sz String Trade size.
> side String Trade direction, buy, sell, from taker perspective.
> ts String Filled time, Unix timestamp format in milliseconds, e.g. 1597026383085.

Block tickers channel

Retrieve the latest block trading volume in the last 24 hours.

The data will be pushed when triggered by transaction execution event. In addition, it will also be pushed in 5 minutes interval according to subscription granularity.

Request Example

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

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, block-tickers
> instId String Yes Instrument ID e.g. BTC-USDT-SWAP

Successful Response Example

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

Failure Response Example

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

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe error
arg Object No Subscribed channel
> channel String Yes Channel name, block-tickers
> instId String Yes Instrument ID
code String No Error code
msg String No Error message

Push Data Example

{
    "arg": {
        "channel": "block-tickers"
    },
    "data": [
        {
            "instType": "SWAP",
            "instId": "LTC-USD-SWAP",
            "volCcy24h": "0",
            "vol24h": "0",
            "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
> instId String Instrument ID
> instType String Instrument type
> volCcy24h String 24h trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of base currency.
If it is SPOT/MARGIN, the value is the quantity in quote currency.
> vol24h String 24h trading volume, with a unit of contract.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the quantity in base currency.
> ts String Block ticker data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085

REST API

Authentication

Generating an API Key

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

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.

Making Requests

All private REST requests must contain the following headers:

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:

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

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

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

The requestPath is the path of requesting an endpoint.

Example: /api/v5/account/balance

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

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

The SecretKey is generated when you create an APIKey.

Example: 22582BD0CFF14C41EDBF1AB98506286D

Trade

All Trade API endpoints require authentication.

Place order

You can place an order only if you have sufficient funds.
For leading contracts, this endpoint supports placement, but can't close positions.

Rate Limit: 60 requests per 2 seconds

Rate Limit of leading contracts for Copy Trading: 1 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/order

Request Example

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

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USD-190927-5000-C
tdMode String Yes Trade mode
Margin mode cross isolated
Non-Margin mode cash
ccy String No Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
posSide String Conditional Position side
The default is net in the net mode
It is required in the long/short mode, and can only be long or short.
Only applicable to FUTURES/SWAP.
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 (applicable only to Futures and Perpetual swap).
sz String Yes Quantity to buy or sell
px String Conditional Order price. Only applicable to limit,post_only,fok,ioc order.
reduceOnly Boolean No Whether orders can only reduce in position size.
Valid options: true or false. The default value is false.
Only applicable to MARGIN orders, and FUTURES/SWAP orders in net mode
Only applicable to Single-currency margin and Multi-currency margin
tgtCcy String No Whether the target currency uses the quote or base currency.
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
banAmend Boolean No Whether to disallow the system from amending the size of the SPOT Market Order.
Valid options: true or false. The default value is false.
If true, system will not amend and reject the market order if user does not have sufficient funds.
Only applicable to SPOT Market Orders
tpTriggerPx String No Take-profit trigger price
If you fill in this parameter, you should fill in the take-profit order price as well.
tpOrdPx String No Take-profit order price
If you fill in this parameter, you should fill in the take-profit trigger price as well.
If the price is -1, take-profit will be executed at the market price.
slTriggerPx String No Stop-loss trigger price
If you fill in this parameter, you should fill in the stop-loss order price.
slOrdPx String No Stop-loss order price
If you fill in this parameter, you should fill in the stop-loss trigger price.
If the price is -1, stop-loss will be executed at the market price.
tpTriggerPxType String No Take-profit trigger price type
last: last price
index: index price
mark: mark price
The Default is last
slTriggerPxType String No Stop-loss trigger price type
last: last price
index: index price
mark: mark price
The Default is last
quickMgnType String No Quick Margin type. Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
The default value is manual

Response Example

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

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
tag String Order tag
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection or success message of event execution.

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.
For leading contracts, this endpoint supports placement, but can't close positions.

Rate Limit: 300 orders per 2 seconds

Rate Limit of leading contracts for Copy Trading: 1 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/batch-orders

Request Example

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

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USD-190927-5000-C
tdMode String Yes Trade mode
Margin mode cross isolated
Non-Margin mode cash
ccy String No Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
posSide String Conditional Position side
The default is net in the net mode
It is required in the long/short mode, and can only be long or short.
Only applicable to FUTURES/SWAP.
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 (applicable only to Futures and Perpetual swap).
sz String Yes Quantity to buy or sell
px String Conditional Order price. Only applicable to limit,post_only,fok,ioc order.
reduceOnly Boolean No Whether the order can only reduce position size.
Valid options: true or false. The default value is false.
Only applicable to MARGIN orders, and FUTURES/SWAP orders in net mode
Only applicable to Single-currency margin and Multi-currency margin
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
tpTriggerPx String No Take-profit trigger price
If you fill in this parameter, you should fill in the take-profit order price as well.
tpOrdPx String No Take-profit order price
If you fill in this parameter, you should fill in the take-profit trigger price as well.
If the price is -1, take-profit will be executed at the market price.
slTriggerPx String No Stop-loss trigger price
If you fill in this parameter, you should fill in the stop-loss order price.
slOrdPx String No Stop-loss order price
If you fill in this parameter, you should fill in the stop-loss trigger price.
If the price is -1, stop-loss will be executed at the market price.
tpTriggerPxType String No Take-profit trigger price type
last: last price
index: index price
mark: mark price
The Default is last
slTriggerPxType String No Stop-loss trigger price type
last: last price
index: index price
mark: mark price
The Default is last
quickMgnType String No Quick Margin type. Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
The default value is manual

Response Example

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

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
tag String Order tag
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection or success message of event execution.

Cancel order

Cancel an incomplete order.

Rate Limit: 60 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/cancel-order

Request Example

POST /api/v5/trade/cancel-order
body
{
    "ordId":"2510789768709120",
    "instId":"BTC-USD-190927"
}

Request Parameters

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

Response Example

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

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection message if the request is unsuccessful.

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 (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "sCode":"0",
            "sMsg":""
        },
     .......
    ]
}

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection message if the request is unsuccessful.

Amend order

Amend an incomplete order.

Rate Limit: 60 requests per 2 seconds

Rate Limit of leading contracts for Copy Trading: 1 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/amend-order

Request Example

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

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
cxlOnFail Boolean No Whether the order needs to be automatically canceled when the order amendment fails
Valid options: false or true, the default is false.
ordId String Conditional Order ID
Either ordId or clOrdId is required. If both are passed, ordId will be used.
clOrdId String Conditional Client Order ID as assigned by the client
reqId String No Client Request ID as assigned by the client for order amendment
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
The response will include the corresponding reqId to help you identify the request if you provide it in the request.
newSz String Conditional New quantity after amendment. When amending a partially-filled order, the newSz should include the amount that has been filled.
newPx String Conditional New price after amendment.
newTpTriggerPx String Conditional Take-profit trigger price.
Either the take profit trigger price or order price is 0, it means that the take profit is deleted
newTpOrdPx String Conditional Take-profit order price
If the price is -1, take-profit will be executed at the market price.
newSlTriggerPx String Conditional Stop-loss trigger price
Either the stop loss trigger price or order price is 0, it means that the stop loss is deleted
newSlOrdPx String Conditional Stop-loss order price
If the price is -1, stop-loss will be executed at the market price.
newTpTriggerPxType String Conditional Take-profit trigger price type
last: last price
index: index price
mark: mark price
newSlTriggerPxType String Conditional Stop-loss trigger price type
last: last price
index: index price
mark: mark price

Response Example

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

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
reqId String Client Request ID as assigned by the client for order amendment.
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection message if the request is unsuccessful.

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 of leading contracts for Copy Trading: 1 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

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

Request Example

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

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 clOrdIdis required, if both are passed, ordId will be used.
clOrdId String Conditional Client Order ID as assigned by the client
reqId String No Client Request ID as assigned by the client for order amendment
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
The response will include the corresponding reqId to help you identify the request if you provide it in the request.
newSz String Conditional New quantity after amendment. When amending a partially-filled order, the newSz should include the amount that has been filled.
newPx String Conditional New price after amendment.
newTpTriggerPx Conditional No Take-profit trigger price.
Either the take-profit trigger price or order price is 0, it means that the take-profit is deleted
newTpOrdPx Conditional No Take-profit order price
If the price is -1, take-profit will be executed at the market price.
newSlTriggerPx Conditional No Stop-loss trigger price
Either the stop-loss trigger price or order price is 0, it means that the stop-loss is deleted
newSlOrdPx Conditional No Stop-loss order price
If the price is -1, stop-loss will be executed at the market price.
newTpTriggerPxType Conditional No Take-profit trigger price type
last: last price
index: index price
mark: mark price
newSlTriggerPxType Conditional No Stop-loss trigger price type
last: last price
index: index price
mark: mark price

Response Example

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

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
reqId String Client Request ID as assigned by the client for order amendment.
sCode String The code of the event execution result, 0 means success.
sMsg String Rejection message if the request is unsuccessful.

Close positions

Close the position of an instrument via a market order.

Rate Limit: 20 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/close-position

Request Example

POST /api/v5/trade/close-position
body
{
    "instId":"BTC-USDT-SWAP",
    "mgnMode":"cross"
}

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
posSide String Conditional Position side
This parameter can be omitted in net mode, and the default value is net. You can only fill with net.
This parameter must be filled in under the long/short mode. Fill in long for close-long and short for close-short.
mgnMode String Yes Margin mode
cross isolated
ccy String Conditional Margin currency, required in the case of closing cross MARGIN position for Single-currency margin.
autoCxl Boolean No Whether any pending orders for closing out needs to be automatically canceled when close position via a market order.
false or true, the default is false.
clOrdId String No Client-supplied ID
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.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT-SWAP",
      "posSide": "long"
    }
  ]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
posSide String Position side
clOrdId String Client-supplied ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
tag String Order tag
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.

Get order details

Retrieve order details.

Rate Limit: 60 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

GET /api/v5/trade/order

Request Example

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

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USD-190927
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",
  "msg": "",
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "ccy": "",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "pnl": "5",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "live",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpTriggerPxType": "last",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slTriggerPxType": "last",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "category": "",
      "reduceOnly": "false",
      "cancelSource": "20",
      "cancelSourceReason": "Cancel all after triggered",
      "quickMgnType": "",
      "algoClOrdId": "",
      "algoId": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
instId String Instrument ID
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
pnl String Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
ordType String Order type
market: Market order
limit: Limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc: Market order with immediate-or-cancel order
side String Order side
posSide String Position side
tdMode String Trade mode
accFillSz String Accumulated fill quantity
The unit is base_ccy for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is base_ccy when the tgtCcy is base_ccy or quote_ccy;
The unit is contract for FUTURES/SWAP/OPTION
fillPx String Last filled price. If none is filled, it will return "".
tradeId String Last traded ID
fillSz String Last filled quantity
The unit is base_ccy for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is base_ccy when the tgtCcy is base_ccy or quote_ccy;
The unit is contract for FUTURES/SWAP/OPTION
fillTime String Last filled time
avgPx String Average filled price. If none is filled, it will return "".
state String State
canceled
live
partially_filled
filled
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
feeCcy String Fee currency
fee String Fee and rebate
For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
For Futures, Swap and Options, it is accumulated fee and rebate
rebateCcy String Rebate currency
source String Order source
13:The generated limit order after the strategy order is triggered
rebate String Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
category String Category
normal
twap
adl
full_liquidation
partial_liquidation
delivery
ddh
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
cancelSource String Code of the cancellation source.
cancelSourceReason String Reason for the cancellation.
quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
algoClOrdId String Client-supplied Algo ID. There will be a value when algo order attaching algoClOrdId is triggered, or it will be "".
algoId String Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get order List

Retrieve all incomplete orders under the current account.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-pending

Request Example

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

Request Parameters

Parameter Type Required Description
instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
uly String No Underlying
instFamily String No Instrument family
Applicable to FUTURES/SWAP/OPTION
instId String No Instrument ID, e.g. BTC-USD-200927
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
optimal_limit_ioc: Market order with 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",
    "msg": "",
    "data": [
        {
            "accFillSz": "0",
            "avgPx": "",
            "cTime": "1618235248028",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "0",
            "feeCcy": "BTC",
            "fillPx": "",
            "fillSz": "0",
            "fillTime": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "5.6",
            "ordId": "301835739059335168",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "net",
            "px": "59200",
            "rebate": "0",
            "rebateCcy": "USDT",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "slTriggerPxType": "last",
            "state": "live",
            "sz": "1",
            "tag": "",
            "tgtCcy": "",
            "tdMode": "cross",
            "source":"",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "last",
            "tradeId": "",
            "reduceOnly": "false",
            "quickMgnType": "",
            "algoClOrdId": "",
            "algoId": "",
            "uTime": "1618235248028"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
pnl String Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
ordType String Order type
market: Market order
limit: Limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc: Market order with immediate-or-cancel order
side String Order side
posSide String Position side
tdMode String Trade mode
accFillSz String Accumulated fill quantity
fillPx String Last filled price
tradeId String Last trade ID
fillSz String Last filled quantity
fillTime String Last filled time
avgPx String Average filled price. If none is filled, it will return "".
state String State
live
partially_filled
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
feeCcy String Fee currency
fee String Fee and rebate
For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
For Futures, Swap and Options, it is accumulated fee and rebate
rebateCcy String Rebate currency
source String Order source
13:The generated limit order after the strategy order is triggered
rebate String Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
category String Category
normal
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
algoClOrdId String Client-supplied Algo ID. There will be a value when algo order attaching algoClOrdId is triggered, or it will be "".
algoId String Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

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

Request Parameters

Parameter Type Required Description
instType String yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
uly String No Underlying
Applicable to FUTURES/SWAP/OPTION
instFamily String No Instrument family
Applicable to FUTURES/SWAP/OPTION
instId String No Instrument ID, e.g. BTC-USD-190927
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
optimal_limit_ioc: Market order with immediate-or-cancel order
state String No State
canceled
filled
category String No Category
twap
adl
full_liquidation
partial_liquidation
delivery
ddh
after String No Pagination of data to return records earlier than the requested ordId
before String No Pagination of data to return records newer than the requested ordId
begin String No Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
end String No Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "ccy": "",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "filled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpTriggerPxType": "last",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slTriggerPxType": "last",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "source":"",
      "rebate": "",
      "tgtCcy":"",
      "pnl": "",
      "category": "",
      "reduceOnly": "false",
      "cancelSource": "20",
      "cancelSourceReason": "Cancel all after triggered",
      "algoClOrdId": "",
      "algoId": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
optimal_limit_ioc: Market order with immediate-or-cancel order
side String Order side
posSide String Position side
tdMode String Trade mode
accFillSz String Accumulated fill quantity
fillPx String Last filled price. If none is filled, it will return "".
tradeId String Last trade ID
fillSz String Last filled quantity
fillTime String Last filled time
avgPx String Average filled price. If none is filled, it will return "".
state String State
canceled
filled
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
feeCcy String Fee currency
fee String Fee and rebate
For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
For Futures, Swap and Options, it is accumulated fee and rebate
rebateCcy String Rebate currency
source String Order source
13:The generated limit order after the strategy order is triggered
rebate String Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
pnl String Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
category String Category
normal
twap
adl
full_liquidation
partial_liquidation
delivery
ddh
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
cancelSource String Code of the cancellation source.
cancelSourceReason String Reason for the cancellation.
algoClOrdId String Client-supplied Algo ID. There will be a value when algo order attaching algoClOrdId is triggered, or it will be "".
algoId String Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get order history (last 3 months)

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

Request Parameters

Parameter Type Required Description
instType String yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
uly String No Underlying
Applicable to FUTURES/SWAP/OPTION
instFamily String No Instrument family
Applicable to FUTURES/SWAP/OPTION
instId String No Instrument ID, e.g. BTC-USD-200927
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
optimal_limit_ioc: Market order with immediate-or-cancel order
state String No State
canceled
filled
category String No Category
twap
adl
full_liquidation
partial_liquidation
delivery
ddh
after String No Pagination of data to return records earlier than the requested ordId
before String No Pagination of data to return records newer than the requested ordId
begin String No Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
end String No Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "ccy": "",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "filled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpTriggerPxType": "last",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slTriggerPxType": "last",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "source":"",
      "rebate": "",
      "tgtCcy":"",
      "pnl": "",
      "category": "",
      "reduceOnly": "false",
      "cancelSource": "20",
      "cancelSourceReason": "Cancel all after triggered",
      "algoClOrdId": "",
      "algoId": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
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
optimal_limit_ioc: Market order with immediate-or-cancel order
side String Order side
posSide String Position side
tdMode String Trade mode
accFillSz String Accumulated fill quantity
fillPx String Last filled price. If none is filled, it will return "".
tradeId String Last trade ID
fillSz String Last filled quantity
fillTime String Last filled time
avgPx String Average filled price. If none is filled, it will return "".
state String State
canceled
filled
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
feeCcy String Fee currency
fee String Fee and rebate
For spot and margin, it is accumulated fee charged by the platform. It is always negative, e.g. -0.01.
For Futures, Swap and Options, it is accumulated fee and rebate
source String Order source
13:The generated limit order after the strategy order is triggered
rebateCcy String Rebate currency
rebate String Rebate amount, only applicable to spot and margin, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "".
pnl String Profit and loss, Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions
category String Category
normal
twap
adl
full_liquidation
partial_liquidation
delivery
ddh
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
cancelSource String Code of the cancellation source.
cancelSourceReason String Reason for the cancellation.
algoClOrdId String Client-supplied Algo ID. There will be a value when algo order attaching algoClOrdId is triggered, or it will be "".
algoId String Algo ID. There will be a value when algo order is triggered, or it will be "".
uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get 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

Request Parameters

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

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
         {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "tradeId":"123",
            "ordId":"123445",
            "clOrdId": "b16",
            "billId":"1111",
            "tag":"",
            "fillPx":"999",
            "fillSz":"3",
            "side":"buy",
            "posSide":"long",
            "execType":"M",             
            "feeCcy":"",
            "fee":"",
            "ts": "1597026383085",
            "fillTime": "1597026383084"
        },
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "tradeId":"123",
            "ordId":"123445",
            "clOrdId": "b16",
            "billId":"1111",
            "tag":"",
            "fillPx":"999",
            "fillSz":"3",
            "side":"buy",
            "posSide":"long",
            "execType":"M",             
            "feeCcy":"",
            "fee":"",
            "ts":"1597026383085",
            "fillTime": "1597026383084"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tradeId String Last trade ID
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
billId String Bill ID
tag String Order tag
fillPx String Last filled price
fillSz String Last filled quantity
side String Order side, buy sell
posSide String Position side
long short
it returns net innet mode.
execType String Liquidity taker or maker, T: taker M: maker
Not applicable to system orders such as ADL and liquidation
feeCcy String Fee currency
fee String Fee
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.

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

Request Parameters

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

Response Example

{
    "code":"0",
    "msg":"",
    "data":[
         {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "tradeId":"123",
            "ordId":"123445",
            "clOrdId": "b16",
            "billId":"1111",
            "tag":"",
            "fillPx":"999",
            "fillSz":"3",
            "side":"buy",
            "posSide":"long",
            "execType":"M",             
            "feeCcy":"",
            "fee":"",
            "ts": "1597026383085",
            "fillTime": "1597026383084"
        },
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "tradeId":"123",
            "ordId":"123445",
            "clOrdId": "b16",
            "billId":"1111",
            "tag":"",
            "fillPx":"999",
            "fillSz":"3",
            "side":"buy",
            "posSide":"long",
            "execType":"M",             
            "feeCcy":"",
            "fee":"",
            "ts": "1597026383085",
            "fillTime": "1597026383084"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tradeId String Last trade ID
ordId String Order ID
clOrdId String Client Order ID as assigned by the client
billId String Bill ID
tag String Order tag
fillPx String Last filled price
fillSz String Last filled quantity
side String Order side, buy sell
posSide String Position side
long short
it returns net innet mode.
execType String Liquidity taker or maker, T: taker M: maker
Not applicable to system orders such as ADL and liquidation
feeCcy String Fee currency
fee String Fee
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.

Place algo order

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

Rate Limit: 20 requests per 2 seconds

Rate Limit of leading contracts for Copy Trading: 1 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/order-algo

Request Example

POST /api/v5/trade/order-algo
body
{
    "instId":"BTC-USDT",
    "tdMode":"cross",
    "side":"buy",
    "ordType":"conditional",
    "sz":"2",
    "tpTriggerPx":"15",
    "tpOrdPx":"18"
}

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USD-190927-5000-C
tdMode String Yes Trade mode
Margin mode cross isolated
Non-Margin mode cash
ccy String No Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
side String Yes Order side, buy sell
posSide String Conditional Position side
Required in long/short mode and only be long or short
ordType String Yes Order type
conditional: One-way stop order
oco: One-cancels-the-other order
trigger: Trigger order
move_order_stop: Trailing order
iceberg: Iceberg order
twap: TWAP order
sz String Conditional Quantity to buy or sell
Either sz or closeFraction is required.
tag String No Order tag
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
reduceOnly Boolean No Whether the order can only reduce the position size.
Valid options: true or false. The default value is false.
Only applicable to MARGIN orders, and FUTURES/SWAP orders in net mode
Only applicable to Single-currency margin and Multi-currency margin
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.
closeFraction String Conditional Fraction of position to be closed when the algo order is triggered.
Currently the system supports fully closing the position only so the only accepted value is 1.
This is only applicable to FUTURES or SWAP instruments.
This is only applicable if posSide is net.
This is only applicable if reduceOnly is true.
This is only applicable if ordType is conditional or oco.
This is only applicable if the stop loss and take profit order is executed as market order
Either sz or closeFraction is required.
quickMgnType String No Quick Margin type. Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
The default value is manual

Stop 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
index: index price
mark: mark price
The Default is last
tpOrdPx String No Take-profit order price
If you fill in this parameter, you should fill in the take-profit trigger price as well.
If the price is -1, take-profit will be executed at the market price.
slTriggerPx String No Stop-loss trigger price
If you fill in this parameter, you should fill in the stop-loss order price.
slTriggerPxType String No Stop-loss trigger price type

last: last price
index: index price
mark: mark price
The Default is last
slOrdPx String No Stop-loss order price
If you fill in this parameter, you should fill in the stop-loss trigger price.
If the price is -1, stop-loss will be executed at the market price.

Trigger Order

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

last: last price
index: index price
mark: mark price
The Default is last

Trailing Stop Order

Parameter Type Required Description
callbackRatio String Conditional Callback price ratio , e.g. 0.01

Either callbackRatio or callbackSpread is allowed to be passed.
callbackSpread String Conditional Callback price variance
activePx String No Active price

Iceberg Order

Parameter Type Required Description
pxVar String Conditional Price ratio
Either pxVar or pxSpread is allowed to be passed.
pxSpread String Conditional Price variance
szLimit String Yes Average amount
pxLimit String Yes Price Limit

TWAP Order

Parameter Type Required Description
pxVar String Conditional Price ratio
Either pxVar or pxSpread is allowed to be passed.
pxSpread String Conditional Price variance
szLimit String Yes Average amount
pxLimit String Yes Price Limit
timeInterval String Yes Time interval

learn more about Iceberg Order & TWAP Order

Response Example

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

Response Parameters

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

Cancel algo order

Cancel unfilled algo orders (not including Iceberg order, TWAP order, Trailing Stop order). A maximum of 10 orders can be canceled per request. Request parameters should be passed in the form of an array.

Rate Limit: 20 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/cancel-algos

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Amend algo order

Amend unfilled algo orders (Support stop order only ,not including Move_order_stop order, Trigger order, Iceberg order, TWAP order, Trailing Stop order).
Only applicable to Futures and Perpetual swap.

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",
    "algoClOrdId":"algo_01"
    "newSz":"2",
    "instId":"BTC-USDT-SWAP",
    "cxlOnFail":false,
    "reqId":"po103ux",
    "newTpTriggerPx":"30000",
    "newTpOrdPx":"30000",
    "newSlTriggerPx":"26000",
    "newSlOrdPx":"26000",
    "newTpTriggerPxType":"last",
    "newSlTriggerPxType":"last"
}

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
algoId String Conditional Algo ID
Either algoId or algoClOrdId is required. If both are passed, algoId will be used.
algoClOrdId String Conditional Client-supplied Algo ID
Either algoId or algoClOrdId is required. If both are passed, algoId will be used.
cxlOnFail Boolean No Whether the order needs to be automatically canceled when the order amendment fails
Valid options: false or true, the default is false.
reqId String Conditional Client Request ID as assigned by the client for order amendment
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
The response will include the corresponding reqId to help you identify the request if you provide it in the request.
newSz String Conditional New quantity after amendment.
newTpTriggerPx String Conditional Take-profit trigger price.
Either the take-profit trigger price or order price is 0, it means that the take-profit is deleted
newTpOrdPx String Conditional Take-profit order price
If the price is -1, take-profit will be executed at the market price.
newSlTriggerPx String Conditional Stop-loss trigger price.
Either the stop-loss trigger price or order price is 0, it means that the stop-loss is deleted
newSlOrdPx String Conditional Stop-loss order price
If the price is -1, stop-loss will be executed at the market price.
newTpTriggerPxType String Conditional Take-profit trigger price type
last: last price
index: index price
mark: mark price
newSlTriggerPxType String Conditional Stop-loss trigger price type
last: last price
index: index price
mark: mark price

Response Example

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

Response Parameters

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

Cancel advance algo order

Cancel unfilled algo orders (including Iceberg order, TWAP order, Trailing Stop order). A maximum of 10 orders can be canceled per request. Request parameters should be passed in the form of an array.

Rate Limit: 20 requests per 2 seconds

Rate limit rule (except Options): UserID + Instrument ID

Rate limit rule (Options only): UserID + Instrument Family

HTTP Request

POST /api/v5/trade/cancel-advance-algos

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

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=1234231231423

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",
    "msg":"",
    "data":[
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ordId":"123445",
            "ccy":"BTC",
            "clOrdId":"",
            "algoId":"1234",
            "sz":"999",
            "closeFraction":"",
            "ordType":"oco",
            "side":"buy",
            "posSide":"long",
            "tdMode":"cross",
            "tgtCcy": "",
            "state":"effective",
            "lever":"20",
            "tpTriggerPx":"",
            "tpTriggerPxType":"",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"",
            "triggerPx":"99",
            "triggerPxType":"last",
            "ordPx":"12",
            "actualSz":"",
            "actualPx":"",
            "actualSide":"",
            "pxVar":"",
            "pxSpread":"",
            "pxLimit":"",
            "szLimit":"",
            "tag": "adadadadad",
            "timeInterval":"",
            "callbackRatio":"",
            "callbackSpread":"",
            "activePx":"",
            "moveTriggerPx":"",
            "reduceOnly": "false",
            "triggerTime":"1597026383085",
            "last": "16012",
            "failCode": "",
            "algoClOrdId": "",
            "cTime":"1597026383000"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
ordId String Order 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
posSide String Position side
tdMode String Trade mode
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
state String State
live
pause
partially_effective
effective
canceled
order_failed
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
triggerPx String trigger price.
triggerPxType String trigger price type.
last: last price
index: index price
mark: mark price
ordPx String Order price
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
triggerTime String Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085
pxVar String Price ratio
Only applicable to iceberg order or twap order
pxSpread String Price variance
Only applicable to iceberg order or twap order
szLimit String Average amount
Only applicable to iceberg order or twap order
pxLimit String Price Limit
Only applicable to iceberg order or twap order
timeInterval String Time interval
Only applicable to twap order
callbackRatio String Callback price ratio
Only applicable to move_order_stop order
callbackSpread String Callback price variance
Only applicable to move_order_stop order
activePx String Active price
Only applicable to move_order_stop order
moveTriggerPx String Trigger price
Only applicable to move_order_stop order
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
last String Last filled price while placing
failCode String It represents that the reason that algo order fails to trigger. It is "" when the state is effective/canceled. There will be value when the state is order_failed, e.g. 51008;
Only applicable to Stop Order, Trailing Stop Order, Trigger order.
algoClOrdId String Client-supplied Algo ID
cTime String Creation time Unix timestamp format in milliseconds, e.g. 1597026383085

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

Request Parameters

Parameter Type Required Description
ordType String Yes Order type
conditional: One-way stop order
oco: One-cancels-the-other order
trigger: Trigger order
move_order_stop: Trailing order
iceberg: Iceberg order
twap: TWAP order
algoId String No Algo ID
algoClOrdId String No Client-supplied Algo ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
instType String No Instrument type
SPOT
SWAP
FUTURES
MARGIN
instId String No Instrument ID, e.g. BTC-USD-190927
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": "",
            "actualSz": "0",
            "algoId": "492453578716610560",
            "cTime": "1663682082511",
            "callbackRatio": "",
            "callbackSpread": "",
            "ccy": "",
            "clOrdId": "hahawang",
            "instId": "BTC-USDT-SWAP",
            "instType": "SWAP",
            "lever": "3",
            "moveTriggerPx": "",
            "ordId": "",
            "ordPx": "",
            "ordType": "conditional",
            "posSide": "long",
            "pxLimit": "",
            "pxSpread": "",
            "pxVar": "",
            "side": "buy",
            "slOrdPx": "-1",
            "slTriggerPx": "22000",
            "slTriggerPxType": "last",
            "state": "live",
            "sz": "10",
            "closeFraction": "",
            "szLimit": "",
            "tag": "",
            "tdMode": "cross",
            "tgtCcy": "",
            "timeInterval": "",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tpTriggerPxType": "",
            "triggerPx": "",
            "reduceOnly": "false",
            "triggerPxType": "",
            "quickMgnType": "",
            "last": "16012",
            "failCode": "",
            "algoClOrdId": "",
            "triggerTime": ""
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
ordId String Order 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
posSide String Position side
tdMode String Trade mode
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT traded with Market order
state String State,live pause partially_effective
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price
slTriggerPx String Stop-loss trigger price
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price
triggerPx String Trigger price
triggerPxType String Trigger price type.
last: last price
index: index price
mark: mark price
ordPx String Order price
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
triggerTime String Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085
pxVar String Price ratio
Only applicable to iceberg order or twap order
pxSpread String Price variance
Only applicable to iceberg order or twap order
szLimit String Average amount
Only applicable to iceberg order or twap order
pxLimit String Price Limit
Only applicable to iceberg order or twap order
timeInterval String Time interval
Only applicable to twap order
callbackRatio String Callback price ratio
Only applicable to move_order_stop order
callbackSpread String Callback price variance
Only applicable to move_order_stop order
activePx String Active price
Only applicable to move_order_stop order
moveTriggerPx String Trigger price
Only applicable to move_order_stop order
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
last String Last filled price while placing
failCode String It represents that the reason that algo order fails to trigger. There will be value when the state is order_failed, e.g. 51008;
For this endpoint, it always is "".
algoClOrdId String Client-supplied Algo ID
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get algo order history

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

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

Parameter Type Required Description
ordType String Yes Order type
conditional: One-way stop order
oco: One-cancels-the-other order
trigger: Trigger order
move_order_stop: Trailing order
iceberg: Iceberg order
twap: TWAP order
state String Conditional State
effective
canceled
order_failed
Either state or algoId is requied
algoId String Conditional Algo ID
Either state or algoId is required.
instType String No Instrument type
SPOT
SWAP
FUTURES
MARGIN
instId String No Instrument ID, e.g. BTC-USD-190927
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",
    "msg":"",
    "data":[
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ordId":"123445",
            "ccy":"BTC",
            "clOrdId":"",
            "algoId":"1234",
            "sz":"999",
            "closeFraction":"",
            "ordType":"oco",
            "side":"buy",
            "posSide":"long",
            "tdMode":"cross",
            "tgtCcy": "",
            "state":"effective",
            "lever":"20",
            "tpTriggerPx":"",
            "tpTriggerPxType":"",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"",
            "triggerPx":"99",
            "triggerPxType":"last",
            "ordPx":"12",
            "actualSz":"",
            "actualPx":"",
            "actualSide":"",
            "pxVar":"",
            "pxSpread":"",
            "pxLimit":"",
            "szLimit":"",
            "tag": "adadadadad",
            "timeInterval":"",
            "callbackRatio":"",
            "callbackSpread":"",
            "activePx":"",
            "moveTriggerPx":"",
            "reduceOnly": "false",
            "triggerTime":"1597026383085",
            "last": "16012",
            "failCode": "",
            "algoClOrdId": "",
            "cTime":"1597026383000"
        },
        {
            "instType":"FUTURES",
            "instId":"BTC-USD-200329",
            "ordId":"123445",
            "ccy":"BTC",
            "clOrdId":"",
            "algoId":"1234",
            "sz":"999",
            "closeFraction":"",
            "ordType":"oco",
            "side":"buy",
            "posSide":"long",
            "tdMode":"cross",
            "tgtCcy": "",
            "state":"effective",
            "lever":"20",
            "tpTriggerPx":"",
            "tpTriggerPxType":"",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "slTriggerPxType":"",
            "triggerPx":"99",
            "triggerPxType":"last",
            "ordPx":"12",
            "actualSz":"",
            "actualPx":"",
            "actualSide":"",
            "pxVar":"",
            "pxSpread":"",
            "pxLimit":"",
            "szLimit":"",
            "tag": "adadadadad",
            "timeInterval":"",
            "callbackRatio":"",
            "callbackSpread":"",
            "activePx":"",
            "moveTriggerPx":"",
            "reduceOnly": "false",
            "triggerTime":"1597026383085",
            "last": "16012",
            "failCode": "",
            "algoClOrdId": "",
            "cTime":"1597026383000"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
ordId String Order 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
posSide String Position side
tdMode String Trade mode
tgtCcy String Order quantity unit setting for sz
base_ccy: Base currency ,quote_ccy: Quote currency
Only applicable to SPOT Market Orders
Default is quote_ccy for buy, base_ccy for sell
state String State
effective
canceled
order_failed
lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
tpTriggerPx String Take-profit trigger price.
tpTriggerPxType String Take-profit trigger price type.
last: last price
index: index price
mark: mark price
tpOrdPx String Take-profit order price.
slTriggerPx String Stop-loss trigger price.
slTriggerPxType String Stop-loss trigger price type.
last: last price
index: index price
mark: mark price
slOrdPx String Stop-loss order price.
triggerPx String trigger price.
triggerPxType String trigger price type.
last: last price
index: index price
mark: mark price
ordPx String Order price
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
triggerTime String Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085
pxVar String Price ratio
Only applicable to iceberg order or twap order
pxSpread String Price variance
Only applicable to iceberg order or twap order
szLimit String Average amount
Only applicable to iceberg order or twap order
pxLimit String Price Limit
Only applicable to iceberg order or twap order
timeInterval String Time interval
Only applicable to twap order
callbackRatio String Callback price ratio
Only applicable to move_order_stop order
callbackSpread String Callback price variance
Only applicable to move_order_stop order
activePx String Active price
Only applicable to move_order_stop order
moveTriggerPx String Trigger price
Only applicable to move_order_stop order
reduceOnly String Whether the order can only reduce the position size. Valid options: true or false.
quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
last String Last filled price while placing
failCode String It represents that the reason that algo order fails to trigger. It is "" when the state is effective/canceled. There will be value when the state is order_failed, e.g. 51008;
Only applicable to Stop Order, Trailing Stop Order, Trigger order.
algoClOrdId String Client Algo Order ID as assigned by the client.
cTime String Creation time Unix timestamp format in milliseconds, e.g. 1597026383085

Get easy convert currency list

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

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

None

Response Example

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

Response Parameters

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

Place easy convert

Convert small currencies to mainstream currencies. Only applicable to the crypto balance less than $10.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/trade/easy-convert

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Get easy convert history

Get the history and status of easy convert trades.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Get one-click repay currency list

Get list of debt currency data and repay currencies. Debt currencies include both cross and isolated debts.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/one-click-repay-currency-list

Request Example

GET /api/v5/trade/one-click-repay-currency-list

Request Parameters

Parameter Type Required Description
debtType String No Debt type
cross: cross
isolated: isolated

Response Example

{
    "code": "0",
    "data": [
        {
            "debtData": [
                {
                    "debtAmt": "29.653478",
                    "debtCcy": "LTC"
                },
                {
                    "debtAmt": "237803.6828295906051002",
                    "debtCcy": "USDT"
                }
            ],
            "debtType": "cross",
            "repayData": [
                {
                    "repayAmt": "0.4978335419825104",
                    "repayCcy": "ETH"
                }
            ]
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
debtData Array Debt currency data list
> debtCcy String Debt currency type
> debtAmt String Debt currency amount
Including principal and interest
debtType String Debt type
cross: cross
isolated: isolated
repayData Array Repay currency data list
> repayCcy String Repay currency type
> repayAmt String Repay currency's available balance amount

Trade one-click repay

Trade one-click repay to repay cross debts. Isolated debts are not applicable. The maximum repayment amount is based on the remaining available balance of funding and trading accounts.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/trade/one-click-repay

Request Example

POST /api/v5/trade/one-click-repay
body
{
    "debtCcy": ["ETH","BTC"], 
    "repayCcy": "USDT" 
}

Request Parameters

Parameter Type Required Description
debtCcy Array Yes Debt currency type
Maximum 5 currencies can be selected in one order. If there are multiple currencies, separate them with commas.
repayCcy String Yes Repay currency type
Only one receiving currency type can be selected in one order and cannot be the same as the small payment currencies.

Response Example

{
    "code": "0",
    "data": [
        {
            "debtCcy": "ETH", 
            "fillDebtSz": "0.01023052",
            "fillRepaySz": "30", 
            "repayCcy": "USDT", 
            "status": "filled",
            "uTime": "1646188520338"
        },
        {
            "debtCcy": "BTC", 
            "fillFromSz": "3",
            "fillToSz": "60,221.15910001",
            "repayCcy": "USDT",
            "status": "filled",
            "uTime": "1646188520338"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
status String Current status of one-click repay
running: Running
filled: Filled
failed: Failed
debtCcy String Debt currency type
repayCcy String Repay currency type
fillDebtSz String Filled amount of debt currency
fillRepaySz String Filled amount of repay currency
uTime String Trade time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get one-click repay history

Get the history and status of one-click repay trades.

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/one-click-repay-history

Request Example

GET /api/v5/trade/one-click-repay-history

Request Parameters

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

Response Example

{
    "code": "0",
    "data": [
        {
            "debtCcy": "USDC",
            "fillDebtSz": "6950.4865447900000000",
            "fillRepaySz": "4.3067975995094930",
            "repayCcy": "ETH",
            "status": "filled",
            "uTime": "1661256148746"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
debtCcy String Debt currency type
debtSz String Amount of debt currency transacted
repayCcy String Repay currency type
repaySz String Amount of repay currency transacted
status String Current status of one-click repay
running: Running
filled: Filled
failed: Failed
uTime String Trade time, Unix timestamp format in milliseconds, e.g. 1597026383085

Funding

The API endpoints of Funding require authentication.

Get currencies

Retrieve a list of all currencies.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/currencies

Request Example

GET /api/v5/asset/currencies

Request Parameters

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

Response Example

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

Response Parameters

Parameter Type Description
ccy String Currency, e.g. BTC
name String Name of currency. There is no related name when it is not shown.
logoLink String Logo link of currency
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
canDep Boolean Availability to deposit from chain.
false: not available true: available
canWd Boolean Availability to withdraw to chain.
false: not available true: available
canInternal Boolean Availability to internal transfer.
false: not available true: available
minDep String Minimum deposit amount of the currency in a single transaction
minWd String Minimum withdrawal amount of the currency in a single transaction
maxWd String Maximum amount of currency withdrawal in a single transaction
wdTickSz String Withdrawal precision, indicating the number of digits after the decimal point.
The withdrawal fee precision kept the same with withdrawal precision.
The accuracy of internal transfer withdrawal is 8 decimal places.
wdQuota String Withdrawal limit in the past 24 hours, unit in USD
usedWdQuota String Amount of currency withdrawal used in the past 24 hours, unit in USD
minFee String Minimum withdrawal fee
maxFee String Maximum withdrawal fee
mainNet Boolean If current chain is main net then return true, otherwise return false
needTag Boolean Whether tag/memo information is required for withdrawal
minDepArrivalConfirm String Minimum number of blockchain confirmations to acknowledge fund deposit. Account is credited after that but the deposit cannot be withdrawn
minWdUnlockConfirm String Minimum number of blockchain confirmations required for withdrawal of a deposit
depQuotaFixed String Fixed deposit limit, unit in USD
Return empty string if there is no deposit limit
usedDepQuotaFixed String Used amount of fixed deposit quota, unit in USD
Return empty string if there is no deposit limit
depQuoteDailyLayer2 String Layer2 network daily deposit limit

Get balance

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

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/balances

Request Example

GET /api/v5/asset/balances

Request Parameters

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

Response Example

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

Response Parameters

Parameter Type Description
ccy String Currency
bal String Balance
frozenBal String Frozen balance
availBal String Available balance
The balance that can be withdrawn or transferred or used for spot trading

Get non-tradable assets

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

{
    "code": "0",
    "data": [{
        "bal": "0.9",
        "canWd": true,
        "ccy": "USD_BSC",
        "chain": "BSC",
        "ctAddr": "197955",
        "fee": "0.1",
        "logoLink": "",
        "minWd": "0",
        "name": "",
        "needTag": false,
        "wdAll": true,
        "wdTickSz": "4"
    }],
    "msg": ""
}

Response Parameters

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

Get account asset valuation

View account asset valuation

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/asset-valuation

Request Example

GET /api/v5/asset/asset-valuation

Request Parameters

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

Response Example

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

Response Parameters

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

Funds transfer

Only API keys with Trade privilege can call this endpoint.

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

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

Rate Limit: 1 request per second

Rate limit rule: UserID + Currency

HTTP Request

POST /api/v5/asset/transfer

Request Example

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

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

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

Request Parameters

Parameter Type Required Description
ccy String Yes Currency, e.g. USDT
amt String Yes Amount to be transferred
from String Yes The remitting account
6: Funding account, 18: Trading account
to String Yes The beneficiary account
6: Funding account, 18: Trading account
subAcct String Conditional Name of the sub-account
When type is 1, 2 or 4, sub-account is required.
type String No Transfer type
0: transfer within account
1: master account to sub-account (Only applicable to API Key from master account)
2: sub-account to master account (Only applicable to API Key from master account)
3: sub-account to master account (Only applicable to APIKey from sub-account)
4: sub-account to sub-account (Only applicable to APIKey from sub-account, and target account needs to be another sub-account which belongs to same master account)
The default is 0.
loanTrans Boolean No Whether or not borrowed coins can be transferred out under Multi-currency margin and Portfolio margin
the default is false
clientId String No Client-supplied ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
omitPosRisk String No Ignore position risk
Default is false
Applicable to Portfolio margin

Response Example

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

Response Parameters

Response Example

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

Get funds transfer state

Retrieve the transfer state data of the last 2 weeks.

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/transfer-state

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Asset bills details

Query the billing record.

Rate Limit: 6 Requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/bills

Request Example

GET /api/v5/asset/bills

GET /api/v5/asset/bills?type=1

Request Parameters

Parameter Type Required Description
ccy String No Currency
type String No Bill type
1: Deposit
2: Withdrawal
13: Canceled withdrawal
20: Transfer to sub account (for master account)
21: Transfer from sub account (for master account)
22: Transfer out from sub to master account (for sub-account)
23: Transfer in from master to sub account (for sub-account)
28: Manually claimed Airdrop
47: System reversal
48: Event Reward
49: Event Giveaway
50: Received from appointments
51: Deducted from appointments
52: Red packet sent
53: Red packet snatched
54: Red packet refunded
61: Conversion
68: Claim rebate card
69: Distribute rebate card
72: Token received
73: Token given away
74: Token refunded
75: Subscription to savings
76: Redemption to savings
77: Distribute
78: Lock up
79: Node voting
80: Staking
81: Vote redemption
82: Staking redemption
83: Staking yield
84: Violation fee
85: PoW mining yield
86: Cloud mining pay
87: Cloud mining yield
88: Subsidy
89: Staking
90: Staking subscription
91: staking redemption
92: Add collateral
93: Redeem collateral
94: Investment
95: Borrower borrows
96: Principal transferred in
97: Borrower transferred loan out
98: Borrower transferred interest out
99: Investor transferred interest in
102: Prepayment penalty transferred in
103: Prepayment penalty transferred out
104: Mortgage fee transferred in
105: Mortgage fee transferred out
106: Overdue fee transferred in
107: Overdue fee transferred out
108: Overdue interest transferred out
109: Overdue interest transferred in
110: Collateral for closed position transferred in
111: Collateral for closed position transferred out
112: Collateral for liquidation transferred in
113: Collateral for liquidation transferred out
114: Insurance fund transferred in
115: Insurance fund transferred out
116: Place an order
117: Fulfill an order
118: Cancel an order
119: Merchants unlock deposit
120: Merchants add deposit
121: FiatGateway Place an order
122: FiatGateway Cancel an order
123: FiatGateway Fulfill an order
124: Jumpstart unlocking
125: Manual deposit
126: Interest deposit
127: Investment fee transferred in
128: Investment fee transferred out
129: Rewards transferred in
130: Transferred from Trading account
131: Transferred to Trading account
132: Frozen by customer service
133: Unfrozen by customer service
134: Transferred by customer service
135: Cross chain exchange
136: Convert
137: ETH 2.0 Subscription
138: ETH 2.0 Swapping
139: ETH 2.0 Earnings
143: System Reverse
144: Transfer out of unified account reserve
145: Reward Expired
146: Customer feedback
147: vested sushi rewards
150: Affiliate commission
151: Referral reward
152: Broker reward
153: Joiner reward
154: Mystery box reward
155: Rewards withdraw
156: Fee rebate
157: Collected crypto
160: Dual Investment subscribe
161: Dual Investment collection
162: Dual Investment profit
163: Dual Investment refund
169: 2022 new year rewards
172: Sub-affiliate commission
173: Fee rebate
174: Pay
175: Locked collateral
176: Loan
177: Added collateral
178: Returned collateral
179: Repayment
180: Unlocked collateral
181: Airdrop Payment
182: Feedback bounty
183: Invite friends rewards
184: Divide the reward pool
185: Broker Convert Reward
186: FreeETH
187: Convert transfer
188: Slot Auction Conversion
189: Mystery box bonus
193: Card payment Buy
195: Untradable asset withdrawal
196: Untradable asset withdrawal revoked
197: Untradable asset deposit
198: Untradable asset collection reduce
199: Untradable asset collection increase
200: Buy
202: Price Lock Subscribe
203: Price Lock Collection
204: Price Lock Profit
205: Price Lock Refund
207: Dual Investment Lite Subscribe
208: Dual Investment Lite Collection
209: Dual Investment Lite Profit
210: Dual Investment Lite Refund
211: Win crypto with Satoshi
212: Multi-collateral loan collateral locked
213: Collateral transfered out from user account
214: Collateral returned to users
215: Multi-collateral loan collateral released
216: Loan transferred to user's account
217: Multi-collateral loan borrowed
218: Multi-collateral loan repaid
219: Repayment transferred from user's account
220: Delisted crypto
221: Blockchain's withdrawal fee
222: Withdrawal fee refund
223: Copy trading profit share
224: Service fee
225: Shark Fin subscribe
226: Shark Fin collection
227: Shark Fin profit
228: Shark Fin refund
229: Airdrop
230: Token migration completed
232: Subsidized interest received
233: Broker rebate compensation
263: Strategy bots profit share
270: DCD broker transfer
271: DCD broker rebate
284: Transfer out trading sub-account
285: Transfer in trading sub-account
286: Transfer out custody funding account
287: Transfer in custody funding account
288: Custody fund delegation
289: Custody fund undelegation
clientId String No Client-supplied ID for transfer or withdrawal
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100. The default is 100.

Response Example

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

Response Parameters

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

Lightning deposits

Users can create up to 10,000 different invoices within 24 hours.

Rate Limit: 2 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-lightning

Request Example

GET /api/v5/asset/deposit-lightning?ccy=BTC&amt=0.01

Request Parameters

Parameter Type Required Description
ccy String Yes Token symbol. Currently only BTC is supported.
amt String Yes Deposit amount between 0.000001 - 0.1
to String No Receiving account
6: Funding account
18: Trading account
If empty, will default to funding account.

Response Example

{
    "code": "0",
    "data": [
        {
            "cTime": "1631171307612",
            "invoice": "lnbc100u1psnnvhtpp5yq2x3q5hhrzsuxpwx7ptphwzc4k4wk0j3stp0099968m44cyjg9sdqqcqzpgxqzjcsp5hzzdszuv6yv6yw5svctl8kc8uv6y77szv5kma2kuculj86tk3yys9qyyssqd8urqgcensh9l4zwlwr3lxlcdqrlflvvlwldutm6ljx486h7lylqmd06kky6scas7warx69sregzrx20ffmsr4sp865x3wasrjd8ttgqrlx3tr"
        }
    ],
    "msg": ""
}

Response Example

Parameter Type Description
invoice String Invoice text
cTime String Invoice creation time

Get deposit address

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

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-address

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Get deposit history

Retrieve the deposit records according to the currency, deposit status, and time range in reverse chronological order. The 100 most recent records are returned by default.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/deposit-history

Request Example


GET /api/v5/asset/deposit-history

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

Request Parameters

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

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
        "actualDepBlkConfirm": "2",
        "amt": "1",
        "areaCodeFrom": "",
        "ccy": "USDT",
        "chain": "USDT-TRC20",
        "depId": "88****33",
        "from": "",
        "fromWdId": "",
        "state": "2",
        "to": "TN4hGjVXMzy*********9b4N1aGizqs",
        "ts": "1674038705000",
        "txId": "fee235b3e812********857d36bb0426917f0df1802"
    },
    {
        "actualDepBlkConfirm": "",
        "amt": "11",
        "areaCodeFrom": "86",
        "ccy": "USDT",
        "chain": "USDT-Omni",
        "depId": "53****85",
        "from": "158****5369",
        "fromWdId": "",
        "state": "2",
        "to": "",
        "ts": "1651809380000",
        "txId": "36532892_**********_0_WALLET"
    }
  ]
}

Response Parameters

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

Withdrawal

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

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/withdrawal

Request Example

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

Request Parameters

Parameter Type Required Description
ccy String Yes Currency, e.g. USDT
amt String Yes Withdrawal amount
dest String Yes Withdrawal method
3: internal
4: on chain
toAddr String Yes If your dest is 4,toAddr should be a trusted crypto currency address. Some crypto currency addresses are formatted as 'address:tag', e.g. 'ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456'
If your dest is 3,toAddr should be a recipient address which can be email, phone or login account name.
fee String Yes Transaction fee
chain String Conditional Chain name
There are multiple chains under some currencies, such as USDT has USDT-ERC20, USDT-TRC20, and USDT-Omni.
If the parameter is not filled in, the default will be the main chain.
When you withdrawal the non-tradable asset, if the parameter is not filled in, the default will be the unique withdrawal chain.
areaCode String Conditional Area code for the phone number
If toAddr is a phone number, this parameter is required.
clientId String No Client-supplied ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

Response Example

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

Response Parameters

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

Lightning withdrawals

The maximum withdrawal amount is 0.1 BTC per request, and 1 BTC in 24 hours. The minimum withdrawal amount is approximately 0.000001 BTC. Sub-account does not support withdrawal.

Rate Limit: 2 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/withdrawal-lightning

Request Example

POST /api/v5/asset/withdrawal-lightning
body
{
    "ccy":"BTC",
    "invoice":"lnbc100u1psnnvhtpp5yq2x3q5hhrzsuxpwx7ptphwzc4k4wk0j3stp0099968m44cyjg9sdqqcqzpgxqzjcsp5hz"
}

Request Parameters

Parameter Type Required Description
ccy String Yes Token symbol. Currently only BTC is supported.
invoice String Yes Invoice text
memo String No Lightning withdrawal memo

Response Example

{
        "code": "0",
        "msg": "",
        "data": [{
                "wdId": "121212",
                "cTime": "1597026383085"
        }]
}

Response Parameters

Parameter Type Description
wdId String Withdrawal ID
cTime String Withdrawal ID creation time

Cancel withdrawal

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

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/cancel-withdrawal

Request Example

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

Request Parameters

Parameter Type Required Description
wdId String Yes Withdrawal ID

Response Example

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

Response Parameters

Parameter Type Description
wdId String Withdrawal ID

Get withdrawal history

Retrieve the withdrawal records according to the currency, withdrawal status, and time range in reverse chronological order. The 100 most recent records are returned by default.

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/withdrawal-history

Request Example


GET /api/v5/asset/withdrawal-history

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

Request Parameters

Parameter Type Required Description
ccy String No Currency, e.g. BTC
wdId String No Withdrawal ID
clientId String No Client-supplied ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
txId String No Hash record of the deposit
type String No Withdrawal type
3: internal transfer
4: withdrawal to chain
state String No Status of withdrawal
-3：canceling
-2：canceled
-1：failed
0：waiting withdrawal
1：withdrawing
2：withdraw success
7: approved
10: waiting transfer
4, 5, 6, 8, 9, 12: waiting mannual review
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1654041600000
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1656633600000
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

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

Response Parameters

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

Get deposit withdraw status

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

Rate Limit: 1 request per 2 seconds

Rate limit rule: UserID

HTTP Request

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

Request Example

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

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

Request Parameters

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

Response Example

{
    "code":"0",
    "data":[
        {
            "wdId": "200045249",
            "txId": "16f3638329xxxxxx42d988f97", // If txId is generated when returning data, it will be returned together
            "state": "Pending withdrawal: Wallet is under maintenance, please wait.",
            "estCompleteTime": "01/09/2023, 8:10:48 PM"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
estCompleteTime String Estimated complete time
The timezone is UTC+8. The format is MM/dd/yyyy, h:mm:ss AM/PM
estCompleteTime is only an approximate estimated time, for reference only.
state String The detailed stage and status of the deposit/withdrawal
The message in front of the colun is the stage; the message after the colun is the ongoing status.
txId String Hash record of the deposit
When retrieving withdrawal status, txId returns blank "". txId will be returned with value if txId is generated for withdrawal at the time.
wdId String Withdrawal ID
When retrieving deposit status, wdId returns blank "".

Small assets convert

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

Rate Limit: 1 request per second

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Convert

The API endpoints of Convert require authentication. Only the assets in the funding account can be used for convert.

Get convert currencies

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/convert/currencies

Request Example

GET /api/v5/asset/convert/currencies

Request Parameters

none

Response Example

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

Response Parameters

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

Get convert currency pair

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Estimate quote

Rate Limit: 10 requests per second

Rate limit rule: UserID

HTTP Request

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

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Convert trade

Rate Limit: 10 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/asset/convert/trade

Request Example

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

Request Parameters

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

Response Example

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

Response Parameters

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

Get convert history

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

GET /api/v5/asset/convert/history

Request Example

GET /api/v5/asset/convert/history

Request Parameters

Parameters Types Required Description
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100. The default is 100.
tag String No Order tag
Applicable to broker user

Response Example

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

Response Parameters

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

Account

The API endpoints of Account require authentication.

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
Request Parameters
Parameters Types Required Description
ccy String No Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH.

Response Example

{
    "code": "0",
    "data": [
        {
            "adjEq": "10679688.0460531643092577",
            "details": [
                {
                    "availBal": "",
                    "availEq": "9930359.9998",
                    "cashBal": "9930359.9998",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "9439737.0772999514",
                    "eq": "9930359.9998",
                    "eqUsd": "9933041.196999946",
                    "frozenBal": "0",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0",
                    "stgyEq":"0",
                    "spotInUseAmt":""
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "frozenBal": "0.0918492093160816",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0",
                    "stgyEq":"0",
                    "spotInUseAmt":""
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718"
        }
    ],
    "msg": ""
}
Response Parameters
Parameters Types Description
uTime String Update time of account information, millisecond format of Unix timestamp, e.g. 1597026383085
totalEq String The total amount of equity in USD
isoEq String Isolated margin equity in USD
Applicable to Single-currency margin and Multi-currency margin and Portfolio margin
adjEq String Adjusted / Effective equity in USD
The net fiat value of the assets in the account that can provide margins for spot, futures, perpetual swap and options under the cross margin mode.
Cause in multi-ccy or PM mode, the asset and margin requirement will all be converted to USD value to process the order check or liquidation.
Due to the volatility of each currency market, our platform calculates the actual USD value of each currency based on discount rates to balance market risks.
Applicable to Multi-currency margin and Portfolio margin
ordFroz String Cross margin frozen for pending orders in USD
Applicable to Multi-currency margin and Portfolio margin
imr String Initial margin requirement in USD
The sum of initial margins of all open positions and pending orders under cross margin mode in USD.
Applicable to Multi-currency margin and Portfolio margin
mmr String Maintenance margin requirement in USD
The sum of maintenance margins of all open positions under cross margin mode in USD.
Applicable to Multi-currency margin and Portfolio margin
mgnRatio String Margin ratio in USD
The index for measuring the risk of a certain asset in the account.
Applicable to Multi-currency margin and Portfolio margin
notionalUsd String Notional value of positions in USD
Applicable to Multi-currency margin and Portfolio margin
details Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> cashBal String Cash balance
> uTime String Update time of currency balance information, Unix timestamp format in milliseconds, e.g. 1597026383085
> isoEq String Isolated margin equity of the currency
Applicable to Single-currency margin and Multi-currency margin and Portfolio margin
> availEq String Available equity of the currency
The balance that can be used on margin or futures/swap trading.
Applicable to Single-currency margin, Multi-currency margin and Portfolio margin
> disEq String Discount equity of the currency in USD.
> availBal String Available balance of the currency
The balance that can be withdrawn or transferred or used on spot trading.
Applicable to Simple, Single-currency margin, Multi-currency margin and Portfolio margin
> frozenBal String Frozen balance of the currency
> ordFrozen String Margin frozen for open orders
> liab String Liabilities of the currency
Applicable to Multi-currency margin and Portfolio margin
> upl String The sum of the unrealized profit & loss of all margin and derivatives positions of the currency.
Applicable to Single-currency margin, Multi-currency margin and Portfolio margin
> uplLiab String Liabilities due to Unrealized loss of the currency
Applicable to Multi-currency margin and Portfolio margin
> crossLiab String Cross liabilities of the currency
Applicable to Multi-currency margin and Portfolio margin
> isoLiab String Isolated liabilities of the currency
Applicable to Multi-currency margin and Portfolio margin
> mgnRatio String Margin ratio of the currency
The index for measuring the risk of a certain asset in the account.
Applicable to Single-currency margin
> interest String Accrued interest of the currency
Applicable to Multi-currency margin and Portfolio margin
> twap String Risk indicator of auto liability repayment
Divided into 5 levels, from 1 to 5, the larger the number, the more likely the auto repayment will be triggered.
Applicable to Multi-currency margin and Portfolio margin and Portfolio margin
> maxLoan String Max loan of the currency
Applicable to cross of Multi-currency margin and Portfolio margin
> eqUsd String Equity in USD of the currency
> notionalLever String Leverage of the currency
Applicable to Single-currency margin
> stgyEq String Strategy equity
> isoUpl String Isolated unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin and Portfolio margin
> spotInUseAmt String Spot in use amount
Applicable to Portfolio margin

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

Parameters Simple Single-currency margin Multi-currency margin
uTime Yes Yes Yes
totalEq Yes Yes Yes
isoEq Yes Yes
adjEq Yes
ordFroz Yes
imr Yes
mmr Yes
mgnRatio Yes
notionalUsd Yes
details
> ccy Yes Yes Yes
> eq Yes Yes Yes
> cashBal Yes Yes Yes
> uTime Yes Yes Yes
> isoEq Yes Yes
> availEq Yes Yes
> disEq Yes Yes Yes
> availBal Yes Yes Yes
> frozenBal Yes Yes Yes
> ordFrozen Yes Yes Yes
> liab Yes
> upl Yes Yes
> uplLiab Yes
> crossLiab Yes
> isoLiab Yes
> mgnRatio Yes
> interest Yes
> twap Yes
> maxLoan Yes
> eqUsd Yes Yes Yes
> notionalLever Yes
> stgyEq Yes Yes Yes
> isoUpl Yes Yes

Get positions

Retrieve information on your positions. When the account is in net mode, net positions will be displayed, and when the account is in long/short mode, long or short positions will be displayed. Return in reverse chronological order using ctime.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/positions

Request Example

Query BTC-USDT position information
GET /api/v5/account/positions?instId=BTC-USDT
Request Parameters
Parameter Type Required Description
instType String No Instrument type
MARGIN
SWAP
FUTURES
OPTION
instId will be checked against instType when both parameters are passed.
instId String No Instrument ID, e.g. BTC-USD-190927-5000-C. Single instrument ID or multiple instrument IDs (no more than 10) separated with comma
posId String No Single position ID or multiple position IDs (no more than 20) separated with comma.
There is attribute expiration, the posId and position information will be cleared if it is more than 30 days after the last close position.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "adl":"1",
      "availPos":"1",
      "avgPx":"2566.31",
      "cTime":"1619507758793",
      "ccy":"ETH",
      "deltaBS":"",
      "deltaPA":"",
      "gammaBS":"",
      "gammaPA":"",
      "imr":"",
      "instId":"ETH-USD-210430",
      "instType":"FUTURES",
      "interest":"0",
      "usdPx":"",
      "last":"2566.22",
      "lever":"10",
      "liab":"",
      "liabCcy":"",
      "liqPx":"2352.8496681818233",
      "markPx":"2353.849",
      "margin":"0.0003896645377994",
      "mgnMode":"isolated",
      "mgnRatio":"11.731726509588816",
      "mmr":"0.0000311811092368",
      "notionalUsd":"2276.2546609009605",
      "optVal":"",
      "pTime":"1619507761462",
      "pos":"1",
      "baseBorrowed": "",
      "baseInterest": "",
      "quoteBorrowed": "",
      "quoteInterest": "",
      "posCcy":"",
      "posId":"307173036051017730",
      "posSide":"long",
      "spotInUseAmt": "",
      "spotInUseCcy": "",
      "bizRefId": "",
      "bizRefType": "",
      "thetaBS":"",
      "thetaPA":"",
      "tradeId":"109844",
      "uTime":"1619507761462",
      "upl":"-0.0000009932766034",
      "uplLastPx":"-0.0000009932766034",
      "uplRatio":"-0.0025490556801078",
      "uplRatioLastPx":"-0.0025490556801078",
      "vegaBS":"",
      "vegaPA":"",
      "closeOrderAlgo":[
          {
              "algoId":"123",
              "slTriggerPx":"123",
              "slTriggerPxType":"mark",
              "tpTriggerPx":"123",
              "tpTriggerPxType":"mark",
              "closeFraction":"0.6"
          },
          {
              "algoId":"123",
              "slTriggerPx":"123",
              "slTriggerPxType":"mark",
              "tpTriggerPx":"123",
              "tpTriggerPxType":"mark",
              "closeFraction":"0.4"
          }
      ]
    }
  ]
}
Response Parameters
Parameter Type Description
instType String Instrument type
mgnMode String Margin mode
cross
isolated
posId String Position ID
posSide String Position side
long, pos is positive
short, pos is positive
net (FUTURES/SWAP/OPTION: positive pos means long position and negative pos means short position. For MARGIN, pos is always positive, posCcy being base currency means long position, posCcy being quote currency means short position.)
pos String Quantity of positions. In the mode of autonomous transfer from position to position, after the deposit is transferred, a position with pos of 0 will be generated
baseBal String Base currency balance, only applicable to MARGIN（Manual transfers and Quick Margin Mode）
quoteBal String Quote currency balance, only applicable to MARGIN（Manual transfers and Quick Margin Mode）
baseBorrowed String Base currency amount already borrowed, only applicable to MARGIN(Quick Margin Mode）
baseInterest String Base Interest, undeducted interest that has been incurred, only applicable to MARGIN(Quick Margin Mode）
quoteBorrowed String Quote currency amount already borrowed, only applicable to MARGIN(Quick Margin Mode）
quoteInterest String Quote Interest, undeducted interest that has been incurred, only applicable to MARGIN(Quick Margin Mode）
posCcy String Position currency, only applicable to MARGIN positions.
availPos String Position that can be closed
Only applicable to MARGIN, FUTURES/SWAP in the long-short mode, OPTION in Simple and isolated OPTION in margin Account.
avgPx String Average open price
markPx String Latest Mark price
upl String Unrealized profit and loss calculated by mark price.
uplRatio String Unrealized profit and loss ratio calculated by mark price.
uplLastPx String Unrealized profit and loss calculated by last price. Main usage is showing, actual value is upl.
uplRatioLastPx String Unrealized profit and loss ratio calculated by last price.
instId String Instrument ID, e.g. BTC-USD-180216
lever String Leverage, not applicable to OPTION
liqPx String Estimated liquidation price
Not applicable to OPTION
imr String Initial margin requirement, only applicable to cross.
margin String Margin, can be added or reduced. Only applicable to isolated.
mgnRatio String Margin ratio
mmr String Maintenance margin requirement
liab String Liabilities, only applicable to MARGIN.
liabCcy String Liabilities currency, only applicable to MARGIN.
interest String Interest. Undeducted interest that has been incurred.
tradeId String Last trade ID
optVal String Option Value, only applicable to OPTION.
notionalUsd String Notional value of positions in USD
adl String Auto-deleveraging (ADL) indicator
Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the adl intensity.
ccy String Currency used for margin
last String Latest traded price
usdPx String USD price
deltaBS String delta：Black-Scholes Greeks in dollars,only applicable to OPTION
deltaPA String delta：Greeks in coins,only applicable to OPTION
gammaBS String gamma：Black-Scholes Greeks in dollars,only applicable to OPTION
gammaPA String gamma：Greeks in coins,only applicable to OPTION
thetaBS String theta：Black-Scholes Greeks in dollars,only applicable to OPTION
thetaPA String theta：Greeks in coins,only applicable to OPTION
vegaBS String vega：Black-Scholes Greeks in dollars,only applicable to OPTION
vegaPA String vega：Greeks in coins,only applicable to OPTION
spotInUseAmt String Spot in use amount
Applicable to Portfolio margin
spotInUseCcy String Spot in use unit, e.g. BTC
Applicable to Portfolio margin
bizRefId String External business id, e.g. experience coupon id
bizRefType String External business type
closeOrderAlgo Array Close position algo orders attached to the position. This array will have values only after you request "Place algo order" with closeFraction=1.
> algoId String Algo ID
> slTriggerPx String Stop-loss trigger price.
> slTriggerPxType String Stop-loss trigger price type.
last：last price
index：index price
mark：mark price
> tpTriggerPx String Take-profit trigger price.
> tpTriggerPxType String Take-profit trigger price type.
last：last price
index：index price
mark：mark price
> closeFraction String Fraction of position to be closed when the algo order is triggered.
cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085
uTime String Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. 1597026383085

Get positions history

Retrieve the updated position data for the last 3 months. Return in reverse chronological order using utime.

Rate Limit: 1 request per 10 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/positions-history

Request Example

GET /api/v5/account/positions-history

Request Parameters

Parameter Type Required Description
instType String No Instrument type
MARGIN
SWAP
FUTURES
OPTION
instId String No Instrument ID, e.g. BTC-USD-SWAP
mgnMode String No Margin mode
cross isolated
type String No The type of closing position
1：Close position partially;2：Close all;3：Liquidation;4：Partial liquidation; 5：ADL;
It is the latest type if there are several types for the same position.
posId String No Position ID. There is attribute expiration, the posId and position information will be cleared if it is more than 30 days after the last close position.
after String No Pagination of data to return records earlier than the requested uTime, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested uTime, 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": [
        {
            "cTime": "1654177169995",
            "ccy": "BTC",
            "closeAvgPx": "29786.5999999789081085",
            "closeTotalPos": "1",
            "instId": "BTC-USD-SWAP",
            "instType": "SWAP",
            "lever": "10.0",
            "mgnMode": "cross",
            "openAvgPx": "29783.8999999995535393",
            "openMaxPos": "1",
            "pnl": "0.00000030434156",
            "pnlRatio": "0.000906447858888",
            "posId": "452587086133239818",
            "direction": "long",
            "triggerPx": "",
            "type": "1",
            "uTime": "1654177174419",
            "uly": "BTC-USD"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
mgnMode String Margin mode
cross isolated
type String The type of closing position
1：Close position partially;2：Close all;3：Liquidation;4：Partial liquidation; 5：ADL;
It is the latest type if there are several types for the same position.
cTime String Created time of position
uTime String Updated time of position
openAvgPx String Average price of opening position
closeAvgPx String Average price of closing position
posId String Position ID
openMaxPos String Max quantity of position
closeTotalPos String Position's cumulative closed volume
pnl String Profit and loss
pnlRatio String P&L ratio
lever String Leverage
direction String Direction: long short
Only applicable to MARGIN/FUTURES/SWAP/OPTION
triggerPx String trigger mark price
liqPx String Estimated liquidation price
uly String Underlying

Get account and position risk

Get account and position risk

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/account/account-position-risk

Request Example

GET /api/v5/account/account-position-risk
Request Parameters
Parameter Type Required Description
instType String No Instrument type
MARGIN
SWAP
FUTURES
OPTION

Response Example

{
    "code":"0",
    "data":[
        {
            "adjEq":"174238.6793649711331679",
            "balData":[
                {
                    "ccy":"BTC",
                    "disEq":"78846.7803721021362242",
                    "eq":"1.3863533369419636"
                },
                {
                    "ccy":"USDT",
                    "disEq":"73417.2495112863300127",
                    "eq":"73323.395564963177146"
                }
            ],
            "posData":[
                {
                    "baseBal": "0.4",
                    "ccy": "",
                    "instId": "BTC-USDT",
                    "instType": "MARGIN",
                    "mgnMode": "isolated",
                    "notionalCcy": "0",
                    "notionalUsd": "0",
                    "pos": "0",
                    "posCcy": "",
                    "posId": "310388685292318723",
                    "posSide": "net",
                    "quoteBal": "0"
                }
            ],
            "ts":"1620282889345"
        }
    ],
    "msg":""
}
Response Parameters
Parameters Types Description
ts String Update time of account information, millisecond format of Unix timestamp, e.g. 1597026383085
adjEq String Adjusted / Effective equity in USD
Applicable to Multi-currency margin and Portfolio margin
balData Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> disEq String Discount equity of the currency in USD.
posData Array Detailed position information in all currencies
> instType String Instrument type
> mgnMode String Margin mode
cross
isolated
> posId String Position ID
> instId String Instrument ID, e.g. BTC-USD-180216
> pos String Quantity of positions contract,In the mode of autonomous transfer from position to position, after the deposit is transferred, a position with pos of 0 will be generated
> baseBal String Base currency balance, only applicable to MARGIN（Manual transfers and Quick Margin Mode）
> quoteBal String Quote currency balance, only applicable to MARGIN（Manual transfers and Quick Margin Mode）
> posSide String Position side
long
short
net (FUTURES/SWAP/OPTION: positive pos means long position and negative pos means short position. MARGIN: posCcy being base currency means long position, posCcy being quote currency means short position.)
> posCcy String Position currency, only applicable to MARGIN positions.
> ccy String Currency used for margin
> notionalCcy String Notional value of positions in coin
> notionalUsd String Notional value of positions in USD

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: 6 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=MARGIN

Request Parameters

Parameter Type Required Description
instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ccy String No Bill currency
mgnMode String No Margin mode
isolated
cross
ctType String No Contract type
linear
inverse
Only applicable to FUTURES/SWAP
type String No Bill type
1: Transfer 2: Trade 3: Delivery 4: Auto token conversion 5: Liquidation 6: Margin transfer 7: Interest deduction 8: Funding fee 9: ADL 10: Clawback 11: System token conversion 12: Strategy transfer 13: ddh 14: Block trade 15: Quick Margin 18: Profit sharing 22: Repay
subType String No Bill subtype
1: Buy 2: Sell 3: Open long 4: Open short 5: Close long 6: Close short 9: Interest deduction for Market loans 11: Transfer in 12: Transfer out 14: Interest deduction for VIP loans 160: Manual margin increase 161: Manual margin decrease 162: Auto margin increase 114: Auto buy 115: Auto sell 118: System token conversion transfer in 119: System token conversion transfer out 100: Partial liquidation close long 101: Partial liquidation close short 102: Partial liquidation buy 103: Partial liquidation sell 104: Liquidation long 105: Liquidation short 106: Liquidation buy 107: Liquidation sell 108:clawback 110: Liquidation transfer in 111: Liquidation transfer out 125: ADL close long 126: ADL close short 127: ADL buy 128: ADL sell 131: ddh buy 132: ddh sell 170: Exercised 171: Counterparty exercised 172: Expired OTM 112: Delivery long 113: Delivery short 117: Delivery/Exercise clawback 173: Funding fee expense 174: Funding fee income 200:System transfer in 201: Manually transfer in 202: System transfer out 203: Manually transfer out 204: block trade buy 205: block trade sell 206: block trade open long 207: block trade open short 208: block trade close open 209: block trade close short 210: Manual Borrowing 211: Manual Repayment 212: Auto borrow 213: Auto repay 16: Repay forcibly 17: Repay interest by borrowing forcibly 224: repayment transfer in 225: repayment transfer out 250: Profit sharing expenses; 251: Profit sharing refund; 252: Profit sharing income;
after String No Pagination of data to return records earlier than the requested bill ID.
before String No Pagination of data to return records newer than the requested bill ID.
begin String No Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
end String No Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100. The default is 100.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
            "bal": "256.27611382",
            "balChg": "256.27611382",
            "billId": "374241568911437826",
            "ccy": "GODS",
            "execType": "",
            "fee": "",
            "from": "1",
            "instId": "",
            "instType": "",
            "mgnMode": "",
            "notes": "From 币币账户",
            "ordId": "",
            "pnl": "",
            "posBal": "",
            "posBalChg": "",
            "subType": "11",
            "sz": "256.27611382",
            "to": "18",
            "ts": "1635498143100",
            "type": "1"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
billId String Bill ID
type String Bill type
subType String Bill subtype
ts String Creation time, Unix timestamp format in milliseconds, e.g.1597026383085
balChg String Change in balance amount at the account level
posBalChg String Change in balance amount at the position level
bal String Balance at the account level
posBal String Balance at the position level
sz String Quantity
ccy String Account balance currency
pnl String Profit and loss
fee String Fee
Negative number represents the user transaction fee charged by the platform.
Positive number represents rebate.
mgnMode String Margin mode
isolated cross
When bills are not generated by position changes, the field returns ""
instId String Instrument ID, e.g. BTC-USD-190927-5000-C
ordId String Order ID
When bill type is not trade, the field returns ""
execType String Liquidity taker or maker, T: taker M: maker
from String The remitting account
6: FUNDING 18: Trading account
Only applicable to transfer. When bill type is not transfer, the field returns "".
to String The beneficiary account
6: FUNDING 18: Trading account
Only applicable to transfer. When bill type is not transfer, the field returns "".
notes String Notes
Only applicable to transfer. When bill type is not transfer, the field returns "".

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: 6 requests per second

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=MARGIN

Request Parameters

Parameter Type Required Description
instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ccy String No Bill currency
mgnMode String No Margin mode
isolated
cross
ctType String No Contract type
linear
inverse
Only applicable to FUTURES/SWAP
type String No Bill type
1: Transfer 2: Trade 3: Delivery 4: Auto token conversion 5: Liquidation 6: Margin transfer 7: Interest deduction 8: Funding fee 9: ADL 10: Clawback 11: System token conversion 12: Strategy transfer 13: ddh 14: Block trade 15: Quick Margin 18: Profit sharing 22: Repay
subType String No Bill subtype
1: Buy 2: Sell 3: Open long 4: Open short 5: Close long 6: Close short 9: Interest deduction for Market loans 11: Transfer in 12: Transfer out 14: Interest deduction for VIP loans 160: Manual margin increase 161: Manual margin decrease 162: Auto margin increase 114: Auto buy 115: Auto sell 118: System token conversion transfer in 119: System token conversion transfer out 100: Partial liquidation close long 101: Partial liquidation close short 102: Partial liquidation buy 103: Partial liquidation sell 104: Liquidation long 105: Liquidation short 106: Liquidation buy 107: Liquidation sell 108:clawback 110: Liquidation transfer in 111: Liquidation transfer out 125: ADL close long 126: ADL close short 127: ADL buy 128: ADL sell 131: ddh buy 132: ddh sell 170: Exercised 171: Counterparty exercised 172: Expired OTM 112: Delivery long 113: Delivery short 117: Delivery/Exercise clawback 173: Funding fee expense 174: Funding fee income 200:System transfer in 201: Manually transfer in 202: System transfer out 203: Manually transfer out 204: block trade buy 205: block trade sell 206: block trade open long 207: block trade open short 208: block trade close open 209: block trade close short 210: Manual Borrowing 211: Manual Repayment 212: Auto borrow 213: Auto repay 16: Repay forcibly 17: Repay interest by borrowing forcibly 224: repayment transfer in 225: repayment transfer out 250: Profit sharing expenses; 251: Profit sharing refund; 252: Profit sharing income;
after String No Pagination of data to return records earlier than the requested bill ID.
before String No Pagination of data to return records newer than the requested bill ID.
begin String No Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
end String No Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100. The default is 100.

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
            "bal": "256.27611382",
            "balChg": "256.27611382",
            "billId": "374241568911437826",
            "ccy": "GODS",
            "execType": "",
            "fee": "",
            "from": "1",
            "instId": "",
            "instType": "",
            "mgnMode": "",
            "notes": "From 币币账户",
            "ordId": "",
            "pnl": "",
            "posBal": "",
            "posBalChg": "",
            "subType": "11",
            "sz": "256.27611382",
            "to": "18",
            "ts": "1635498143100",
            "type": "1"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
billId String Bill ID
type String Bill type
subType String Bill subtype
ts String Creation time, Unix timestamp format in milliseconds, e.g.1597026383085
balChg String Change in balance amount at the account level
posBalChg String Change in balance amount at the position level
bal String Balance at the account level
posBal String Balance at the position level
sz String Quantity
ccy String Account balance currency
pnl String Profit and loss
fee String Fee
Negative number represents the user transaction fee charged by the platform.
Positive number represents rebate.
mgnMode String Margin mode
isolated cross
When bills are not generated by position changes, the field returns ""
instId String Instrument ID, e.g. BTC-USD-190927-5000-C
ordId String Order ID
When bill type is not trade, the field returns ""
execType String Liquidity taker or maker, T: taker M: maker
from String The remitting account
6: FUNDING 18: Trading account
Only applicable to transfer. When bill type is not transfer, the field returns "".
to String The beneficiary account
6: FUNDING 18: Trading account
Only applicable to transfer. When bill type is not transfer, the field returns "".
notes String Notes
Only applicable to transfer. When bill type is not transfer, the field returns "".

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

Request Parameters

none

Response Example

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "autoLoan": true,
            "ctIsoMode": "automatic",
            "greeksType": "PA",
            "level": "Lv1",
            "levelTmp": "",
            "mgnIsoMode": "automatic",
            "posMode": "net_mode",
            "spotOffsetType": "",
            "uid": "44705892343619584",
            "label": "V5 Test",
            "roleType": "0",
            "traderInsts": [],
            "opAuth": "0",
            "ip": "120.255.24.182,49.245.196.13",
            "perm": "read_only,withdraw,trade",
            "mainUid": "444810535339712570"
        }
    ],
    "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 level
1: Simple 2: Single-currency margin 3: Multi-currency margin 4: Portfolio margin
posMode String Position mode
long_short_mode: long/short, only applicable to FUTURES/SWAP
net_mode: net
autoLoan Boolean Whether to borrow coins automatically
true: borrow coins automatically false: not borrow coins automatically
greeksType String Current display type of Greeks
PA: Greeks in coins BS: Black-Scholes Greeks in dollars
level String The user level of the current real trading volume on the platform, e.g lv1
levelTmp String Temporary experience user level of special users, e.g lv3
ctIsoMode String Contract isolated margin trading settings
automatic: Auto transfers autonomy: Manual transfers
mgnIsoMode String Margin isolated margin trading settings
automatic: Auto transfers; autonomy: Manual transfers; quick_margin: Quick Margin Mode (For new accounts, including subaccounts, some defaults will be automatic, and others will be quick_margin)
spotOffsetType String Risk offset type
1: Spot-Derivatives(USDT) to be offsetted
2: Spot-Derivatives(Coin) to be offsetted
3: Only derivatives to be offsetted
Only applicable to Portfolio margin
roleType String Role type.
0: General user; 1: Leading trader; 2: Copy trader
traderInsts Array Leading trade instruments, only applicable to Leading trader
opAuth String Whether the optional trading was activated
0 not activate, 1 activated
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 urrent request API Key. read_only：Read only；trade ：Trade; withdraw: Withdraw

Set position mode

Single-currency mode and Multi-currency mode: FUTURES and SWAP support both long/short mode and net mode. In net mode, users can only have positions in one direction; In long/short mode, users can hold positions in long and short directions.
Portfolio margin mode: FUTURES and SWAP only support net mode

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-position-mode

Request Example

POST /api/v5/account/set-position-mode
body 
{
    "posMode":"long_short_mode"
}

Request Parameters

Parameter Type Required Description
posMode String Yes Position mode
long_short_mode: long/short, only applicable to FUTURES/SWAP
net_mode: net

Response Example

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

Response Parameters

Parameter Type Description
posMode String Position mode

Set leverage


There are 10 different scenarios for leverage setting:

1. Set leverage for MARGIN instruments under isolated-margin trade mode at pairs level.
2. Set leverage for MARGIN instruments under cross-margin trade mode and Single-currency margin account mode at pairs level.
3. Set leverage for MARGIN instruments under cross-margin trade mode and Multi-currency margin at currency level.
4. Set leverage for MARGIN instruments under cross-margin trade mode and Portfolio margin at currency level.
5. Set leverage for FUTURES instruments under cross-margin trade mode at underlying level.
6. Set leverage for FUTURES instruments under isolated-margin trade mode and buy/sell position mode at contract level.
7. Set leverage for FUTURES instruments under isolated-margin trade mode and long/short position mode at contract and position side level.
8. Set leverage for SWAP instruments under cross-margin trade at contract level.
9. Set leverage for SWAP instruments under isolated-margin trade mode and buy/sell position mode at contract level.
10. Set leverage for SWAP instruments under isolated-margin trade mode and long/short position mode at contract and position side level.

Note that the request parameter posSide is only required when margin mode is isolated in long/short position mode for FUTURES/SWAP instruments (see scenario 7 and 10 above).
Please refer to the request examples on the right for each case.

Rate limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-leverage

Request Example

# 1. Set leverage for `MARGIN` instruments under `isolated-margin` trade mode at pairs level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "lever":"5",
    "mgnMode":"isolated"
}

# 2. Set leverage for `MARGIN` instruments under `cross-margin` trade mode and Single-currency margin account mode at pairs level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "lever":"5",
    "mgnMode":"cross"
}

# 3. Set leverage for `MARGIN` instruments under `cross-margin` trade mode and Multi-currency margin at currency level.
POST /api/v5/account/set-leverage
body
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}

# 4. Set leverage for `MARGIN` instruments under `cross-margin` trade mode and Portfolio margin at currency level.
POST /api/v5/account/set-leverage
body
{
    "ccy":"BTC",
    "lever":"5",
    "mgnMode":"cross"
}

# 5. Set leverage for `FUTURES` instruments under `cross-margin` trade mode at underlying level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "mgnMode":"cross"
}

# 6. Set leverage for `FUTURES` instruments under `isolated-margin` trade mode and buy/sell order placement mode at contract level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "mgnMode":"isolated"
}

# 7. Set leverage for `FUTURES` instruments under `isolated-margin` trade mode and long/short order placement mode at contract and position side level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-200802",
    "lever":"5",
    "posSide":"long",
    "mgnMode":"isolated"
}

# 8. Set leverage for `SWAP` instruments under `cross-margin` trade at contract level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "mgnMode":"cross"
}

# 9. Set leverage for `SWAP` instruments under `isolated-margin` trade mode and buy/sell order placement mode at contract level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "mgnMode":"isolated"
}

# 10. Set leverage for `SWAP` instruments under `isolated-margin` trade mode and long/short order placement mode at contract and position side level.
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT-SWAP",
    "lever":"5",
    "posSide":"long",
    "mgnMode":"isolated"
}

Request Parameters

Parameter Type Required Description
instId String Conditional Instrument ID
Either instId or ccy is required; if both are passed, instId will be used by default.
ccy String Conditional Currency used for margin
Only applicable to cross MARGIN of Multi-currency margin and Portfolio margin
Required when setting the leverage for automatically borrowing coin.
lever String Yes Leverage
mgnMode String Yes Margin mode
isolated cross
Can only be cross if ccy is passed.
posSide String Conditional Position side
long short
Only required when margin mode is isolated in long/short mode for FUTURES/SWAP.

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "lever": "30",
      "mgnMode": "isolated",
      "instId": "BTC-USDT-SWAP",
      "posSide": "long"
    }
  ]
}

Response Parameters

Parameter Type Description
lever String Leverage
mgnMode String Margin mode
cross isolated
instId String Instrument ID
posSide String Position side

Get maximum buy/sell amount or open amount

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/max-size

Request Example

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

Request Parameters

Parameter Type Required Description
instId String Yes Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT,ETH-USDT
tdMode String Yes Trade mode
cross isolated cash
ccy String Conditional Currency used for margin
Only applicable to MARGIN of Single-currency margin.
px String No Price
When the price is not specified, it will be calculated according to the last traded price.
The parameter will be ignored when multiple instruments are specified.
leverage String No Leverage for instrument
The default is current leverage
Only applicable to MARGIN/FUTURES/SWAP
unSpotOffset Boolean No true: disable Spot-Derivatives risk offset, false: enable Spot-Derivatives risk offset
Default is false
Applicable to `Portfolio
It is effective when Spot-Derivatives risk offset is turned on, otherwise this parameter is ignored.

Response Example

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

Response Parameters

Parameter Type Description
instId String Instrument ID
ccy String Currency used for margin
maxBuy String SPOT/MARGIN: The maximum quantity in base currency that you can buy
The cross margin order under Single-currency margin mode, number of coins is based on base currency.
FUTURES/SWAP/OPTIONS: The maximum number of contracts that you can buy
maxSell String SPOT/MARGIN: The maximum quantity in quote currency that you can sell
The cross margin order under Single-currency margin mode, number of coins is based on base currency.
FUTURES/SWAP/OPTIONS: The maximum number of contracts that you can sell

Get maximum available tradable amount

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 when cross MARGIN BTC-USDT use BTC as margin
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross&ccy=BTC

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

Request Parameters

Parameter Type Required Description
instId String Yes Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT,ETH-USDT
ccy String Conditional Currency used for margin
Only applicable to cross MARGIN of Single-currency margin.
tdMode String Yes Trade mode
cross isolated cash
reduceOnly Boolean No Whether to reduce position only
Only applicable to MARGIN
unSpotOffset Boolean No true: disable Spot-Derivatives risk offset, false: enable Spot-Derivatives risk offset
Default is false
Only applicable to Portfolio margin
It is effective when Spot-Derivatives risk offset is turned on, otherwise this parameter is ignored.
quickMgnType String No Quick Margin type. Only applicable to Quick Margin Mode of isolated margin
manual, auto_borrow, auto_repay
The default value is manual

Response Example

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

Response Parameters

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

Increase/decrease margin

Increase or decrease the margin of the isolated position. Margin reduction may result in the change of the actual leverage.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/position/margin-balance

Request Example

POST /api/v5/account/position/margin-balance 
body
{
    "instId":"BTC-USDT-200626",
    "posSide":"short",
    "type":"add",
    "amt":"1"
}

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
posSide String Yes Position side, the default is net
long
short
net
type String Yes add: add margin, or transfer collaterals in (Quick Margin Mode)
reduce: reduce margin, transfer collaterals out (Quick Margin Mode)
amt String Yes Amount to be increased or decreased.
ccy String No Currency, only applicable to MARGIN（Manual transfers and Quick Margin Mode）
auto Boolean No Automatic loan transfer out, true or false, the default is false
only applicable to MARGIN（Manual transfers）
loanTrans Boolean No Whether or not borrowed coins can be transferred out under Multi-currency margin and Portfolio margin
the default is false

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
            "amt": "0.3",
            "ccy": "BTC",
            "instId": "BTC-USDT",
            "leverage": "",
            "posSide": "net",
            "type": "add"
        }]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
posSide String Position side, long short
amt String Amount to be increase or decrease
type String add: add margin
reduce: reduce margin
leverage String Real leverage after the margin adjustment
ccy String Currency

Get leverage

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/leverage-info

Request Example

GET /api/v5/account/leverage-info?instId=BTC-USDT-200626&mgnMode=cross

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
Single instrument ID or multiple instrument IDs (no more than 20) separated with comma
mgnMode String Yes Margin mode
cross isolated

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "instId": "BTC-USDT-200626",
        "mgnMode": "cross",
        "posSide": "long",
        "lever": "10"
    },{
        "instId": "BTC-USDT-200626",
        "mgnMode": "cross",
        "posSide": "short",
        "lever": "10"
    }]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
mgnMode String Margin mode
posSide String Position side
long
short
net
In long/short mode, the leverage in both directions long short will be returned.
lever String Leverage

Get the maximum loan of instrument

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/max-loan

Request Example

Max loan of isolated `MARGIN` in `Single-currency margin`
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=isolated

Max loan of cross `MARGIN` in `Single-currency margin` (Margin Currency is BTC)
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross&mgnCcy=BTC

Max loan of cross `MARGIN` in `Multi-currency margin`
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross

Request Parameters

Parameter Type Required Description
instId String Yes Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT,ETH-USDT
mgnMode String Yes Margin mode
isolated cross
mgnCcy String Conditional Margin currency
Only applicable to cross MARGIN in Single-currency margin

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.1",
      "ccy": "BTC",
      "side": "sell"
    },
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.2",
      "ccy": "USDT",
      "side": "buy"
    }
  ]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
mgnMode String Margin mode
mgnCcy String Margin currency
maxLoan String Max loan
ccy String Currency
side String Order side
buy sell

Get fee rates

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/trade-fee

Request Example

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

Request Parameters

Parameter Type Required Description
instType String Yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
instId String No Instrument ID, e.g. BTC-USDT
Applicable to SPOT/MARGIN
uly String No Underlying, e.g. BTC-USD
Applicable to FUTURES/SWAP/OPTION
instFamily String No Instrument family, e.g. BTC-USD
Applicable to FUTURES/SWAP/OPTION

Response Example

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

Response Parameters

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

Get interest accrued data

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/interest-accrued

Request Example

GET /api/v5/account/interest-accrued

Request Parameters

Parameter Type Required Description
type String No Loan type
1: VIP loans
2: Market loans
Default is Market loans
ccy String No Loan currency, e.g. BTC
Only applicable to Market loans
Only applicable toMARGIN
instId String No Instrument ID, e.g. BTC-USDT
Only applicable to Market loans
mgnMode String No Margin mode
cross
isolated
Only applicable to Market loans
after String No Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested, 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": [
        {
            "ccy": "USDT",
            "instId": "",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "mgnMode": "",
            "ts": "1637312400000",
            "type": "1"
        }
        {
            "ccy": "USDT",
            "instId": "",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "mgnMode": "",
            "ts": "1637049600000",
            "type": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
type String Loan type
1: VIP loans
2: Market loans
ccy String Loan currency, e.g. BTC
instId String Instrument ID, e.g. BTC-USDT
Only applicable to Market loans
mgnMode String Margin mode
cross
isolated
interest String Interest
interestRate String Interest rate (in hour)
liab String Liability
ts String Timestamp for interest accured, Unix timestamp format in milliseconds, e.g. 1597026383085

Get interest rate

Get the user's current leveraged currency borrowing interest rate

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/account/interest-rate

Request Example

GET /api/v5/account/interest-rate
Request Parameters
Parameters Types Required Description
ccy String No Currency, e.g. BTC 
{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ccy":"BTC",
            "interestRate":"0.0001"
        },
        {
            "ccy":"LTC",
            "interestRate":"0.0003"
        }
    ]
}

Response Parameters

Parameter Type Description
interestRate String interest rate
ccy String currency

Set greeks (PA/BS)

Set the display type of Greeks.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-greeks

Request Example

POST /api/v5/account/set-greeks 
body
{
    "greeksType":"PA"
}

Request Parameters

Parameter Type Required Description
greeksType String Yes Display type of Greeks.
PA: Greeks in coins
BS: Black-Scholes Greeks in dollars

Response Example

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

Response Parameters

Parameter Type Description
greeksType String Display type of Greeks.

Isolated margin trading settings

You can set the currency margin and futures/perpetual Isolated margin trading mode

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-isolated-mode

Request Example

POST /api/v5/account/set-isolated-mode
body
{
    "isoMode":"automatic",
    "type":"MARGIN"
}

Request Parameters

Parameter Type Required Description
isoMode String Yes Isolated margin trading settings
automatic:Auto transfers
autonomy:Manual transfers
quick_margin:Quick Margin Mode
type String Yes Instrument type

MARGIN
CONTRACTS

Response Example

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

Response Parameters

Parameter Type Description
isoMode String Isolated margin trading settings
automatic:Auto transfers
autonomy:Manual transfers
quick_margin:Quick Margin Mode

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

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",
            "maxWdEx": "125",
            "spotOffsetMaxWd": "",
            "spotOffsetMaxWdEx": ""
        },
        {
            "ccy": "ETH",
            "maxWd": "10",
            "maxWdEx": "12",
            "spotOffsetMaxWd": "",
            "spotOffsetMaxWdEx": ""
        }
    ]
}

Response Parameters

Parameter Type Description
ccy String Currency
maxWd String Max withdrawal (excluding borrowed assets under Multi-currency margin)
maxWdEx String Max withdrawal (including borrowed assets under Multi-currency margin)
spotOffsetMaxWd String Max withdrawal under Spot-Derivatives risk offset mode (excluding borrowed assets under Portfolio margin)
Applicable to Portfolio margin
spotOffsetMaxWdEx String Max withdrawal under Spot-Derivatives risk offset mode (including borrowed assets under Portfolio margin)
Applicable to Portfolio margin

Get account risk state

Only applicable to Portfolio margin account

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/account/risk-state

Request Example

GET /api/v5/account/risk-state

Response Example

{
    "code": "0",
    "data": [
        {
            "atRisk": false,
            "atRiskIdx": [],
            "atRiskMgn": [],
            "ts": "1635745078794"
        }
    ],
    "msg": ""
}
Response Parameters
Parameters Types Description
atRisk String Account risk status in auto-borrow mode
true： the account is currently in a specific risk state
false： the account is currently not in a specific risk state
atRiskIdx Array derivatives risk unit list
atRiskMgn Array margin risk unit list
ts String Unix timestamp format in milliseconds, e.g.1597026383085

Manual borrow and repay in Quick Margin Mode

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/quick-margin-borrow-repay

Request Example

POST /api/v5/account/quick-margin-borrow-repay 
body
{
    "instId":"BTC-USDT",
    "ccy":"USDT",
    "side":"borrow",
    "amt":"100"
}

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USDT
ccy String Yes Loan currency, e.g. BTC
side String Yes borrow repay
amt String Yes borrow/repay amount

Response Example

{
    "code": "0",
    "data": [
        {
            "amt": "100",
            "instId":"BTC-USDT",
            "ccy": "USDT",
            "side": "borrow"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
instId String Instrument ID, e.g. BTC-USDT
ccy String Loan currency, e.g. BTC
side String borrow repay
amt String borrow/repay amount

Get borrow and repay history in Quick Margin Mode

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/quick-margin-borrow-repay-history

Request Example

GET /api/v5/account/quick-margin-borrow-repay-history

Request Parameters

Parameter Type Required Description
instId String No Instrument ID, e.g. BTC-USDT
ccy String No Loan currency, e.g. BTC
side String No borrow repay
after String No Pagination of data to return records earlier than the requested refId
before String No Pagination of data to return records newer than the requested refId
begin String No Filter with a begin timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
end String No Filter with an end timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
    "code": "0",
    "data": [
        {
            "instId": "BTC-USDT",
            "ccy": "USDT",
            "side": "borrow",
            "accBorrowed": "0.01",
            "amt": "0.005",
            "refId": "1637310691470124",
            "ts": "1637310691470"
        },
        {
            "instId": "BTC-USDT",
            "ccy": "USDT",
            "side": "borrow",
            "accBorrowed": "0.01",
            "amt": "0.005",
            "refId": "1637310691470123",
            "ts": "1637310691400"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
instId String Instrument ID, e.g. BTC-USDT
ccy String Loan currency, e.g. BTC
side String borrow repay
accBorrowed String Accumulate borrow amount
amt String borrow/repay amount
refId String The ID of borrowing or repayment
ts String Timestamp for Borrow/Repay

VIP loans borrow and repay

Maximum number of borrowing orders for a single currency is 20

Rate Limit: 6 requests per second

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/borrow-repay

Request Example

POST /api/v5/account/borrow-repay 
body
{
    "ccy":"USDT",
    "side":"borrow",
    "amt":"100",
    "ordId":"1234113444"
}

Request Parameters

Parameter Type Required Description
ccy String Yes Loan currency, e.g. BTC
side String Yes borrow repay
amt String Yes borrow/repay amount
ordId String Conditional Order ID of borrowing, it is necessary while repaying

Response Example

{
    "code": "0",
    "data": [
        {
            "amt": "70809.316200",
            "ccy": "USDT",
            "ordId": "544199684697214976",
            "side": "borrow",
            "state": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ccy String Loan currency, e.g. BTC
side String borrow repay
amt String Already borrow/repay amount
ordId String Order ID of borrowing
state String State
1:Borrowing
2:Borrowed
3:Repaying
4:Repaid
5:Borrow failed

Get borrow and repay history for VIP loans

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/borrow-repay-history

Request Example

GET /api/v5/account/borrow-repay-history

Request Parameters

Parameter Type Required Description
ccy String No Loan currency, e.g. BTC
after String No Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested, 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": [
        {
            "ccy": "USDT",
            "tradedLoan": "102",
            "ts": "1637310691470",
            "type": "2",
            "usedLoan": "97"
        },
        {
            "ccy": "USDT",
            "tradedLoan": "102",
            "ts": "1637050435058",
            "type": "2",
            "usedLoan": "199"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ccy String Loan currency, e.g. BTC
type String Type
1: borrow
2: repay
3: Loan reversed, lack of balance for interest
tradedLoan String Borrow/Repay amount
usedLoan String Borrowed amount for current account
ts String Timestamp for Borrow/Repay

Get VIP interest accrued data

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/vip-interest-accrued

Request Example

GET /api/v5/account/vip-interest-accrued

Request Parameters

Parameter Type Required Description
ccy String No Loan currency, e.g. BTC
Only applicable toMARGIN
ordId String No Order ID of borrowing
after String No Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested, 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": [
        {
            "ccy": "USDT",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "ordId": "16373124000001235",
            "ts": "1637312400000"
        },
        {
            "ccy": "USDT",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "ordId": "16370496000001234",
            "ts": "1637049600000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ordId String Order ID of borrowing
ccy String Loan currency, e.g. BTC
interest String Interest
interestRate String Interest rate (in hours)
liab String Liability
ts String Timestamp for interest accrued, Unix timestamp format in milliseconds, e.g. 1597026383085

Get VIP interest deducted data

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/vip-interest-deducted

Request Example

GET /api/v5/account/vip-interest-deducted

Request Parameters

Parameter Type Required Description
ccy String No Loan currency, e.g. BTC
Only applicable toMARGIN
ordId String No Order ID of borrowing
after String No Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested, 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": [
        {
            "ccy": "USDT",
            "interest": "0.0003960833333334",
            "interestRate": "0.0000040833333333",
            "liab": "97",
            "ordId": "16373124000001235",
            "ts": "1637312400000"
        },
        {
            "ccy": "USDT",
            "interest": "0.0004083333333334",
            "interestRate": "0.0000040833333333",
            "liab": "100",
            "ordId": "16370496000001234",
            "ts": "1637049600000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ordId String Order ID of borrowing
ccy String Loan currency, e.g. BTC
interest String Interest
interestRate String Interest rate (in hour)
liab String Liability
ts String Timestamp for interest accured, Unix timestamp format in milliseconds, e.g. 1597026383085

Get VIP loan order list

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/vip-loan-order-list

Request Example

GET /api/v5/account/vip-loan-order-list

Request Parameters

Parameter Type Required Description
ordId String No Order ID of borrowing
state String No State 1:Borrowing 2:Borrowed 3:Repaying 4:Repaid 5:Borrow failed
ccy String No Loan currency, e.g. BTC
after String No Pagination of data to return records earlier than the requested ordId
before String No Pagination of data to return records newer than the requested ordId
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
         {
            "borrowAmt": "1.5000000000000000",
            "ccy": "USDT",
            "curRate": "0.0000169999999992",
            "dueAmt": "0.0000000000000000",
            "nextRefreshTime": "1688172235000",
            "ordId": "584301085292781568",
            "origRate": "0.0000169999999992",
            "repayAmt": "1.5000000000000000",
            "state": "4",
            "ts": "1685580235000"
        }
   ]
}

Response Parameters

Parameter Type Description
ts String Operation time, unix timestamp format in milliseconds, e.g. 1597026383085
nextRefreshTime String Next interest rate refresh time, unix timestamp format in milliseconds, e.g. 1597026383085
ccy String Loan currency, e.g. BTC
ordId String Order ID
state String State
1:Borrowing 2:Borrowed 3:Repaying 4:Repaid 5:Borrow failed
origRate String Original rate of order
curRate String Current rate of ccy
dueAmt String Amount due
borrowAmt String Amount borrowed
repayAmt String Amount repaid

Get VIP loan order detail

Rate limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/vip-loan-order-detail

Request Example

GET /api/v5/account/vip-loan-order-detail

Request Parameters

Parameter Type Required Description
ordId String yes Order ID of loan
ccy String No Loan currency, e.g. BTC
after String No Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "amt": "1.5000000000000000",
            "ccy": "USDT",
            "failReason": "",
            "rate": "0.0000000000000000",
            "ts": "1685580264572",
            "type": "2"
        }
   ]
}

Response Parameters

Parameter Type Description
ts String Operation time
ccy String Loan currency, e.g. BTC
type String Operation Type:
1:Borrow
2:Repayment
3:System Repayment
4:Interest Rate Refresh
rate String Current order rate
amt String Borrow/repay amount
failReason String Fail reason

Get borrow interest and limit

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/interest-limits

Request Example

GET /api/v5/account/interest-limits?type=1&ccy=BTC

Request Parameters

Parameter Type Required Description
type String No Loan type
1: VIP loans
2: Market loans
Default is Market loans
ccy String No Loan currency, e.g. BTC

Response Example

{
    "code": "0",
    "data": [
        {
            "debt": "97.06402000000000000000000000000000",
            "interest": "",
            "nextDiscountTime": "1637312400000",
            "nextInterestTime": "1637312400000",
            "loanAlloc": "",
            "records": [
                {
                    "availLoan": "0.0000000000000000",
                    "ccy": "BTC",
                    "interest": "",
                    "loanQuota": "120.0000000000000000",
                    "posLoan": "0",
                    "rate": "0.00199200",
                    "surplusLmt": "120.0000000000000000",
                    "usedLmt": "0",
                    "usedLoan": "0.0000000000000000"
                }
            ]
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
debt String Current debt in USDT
interest String Current interest in USDT, the unit is USDT
Only applicable to Market loans
nextDiscountTime String Next deduct time, Unix timestamp format in milliseconds, e.g. 1597026383085
nextInterestTime String Next accrual time, Unix timestamp format in milliseconds, e.g. 1597026383085
loanAlloc String VIP Loan allocation for the current trading account
1. The unit is percent(%). Range is [0, 100]. Precision is 0.01%
2. If master account did not assign anything, then "0"
3. "" if shared between master and sub-account
records Array Details for currencies
> ccy String Loan currency, e.g. BTC
> rate String Current daily rate
> loanQuota String Borrow limit of master account
If loanAlloc is not "", then it is the borrow limit of the current trading account
> surplusLmt String Available amount across all sub-accounts
If loanAlloc is not "", then it is the available amount to borrow by the current trading account
> usedLmt String Borrowed amount across all sub-accounts
If loanAlloc is not "", then it is the borrowed amount by the current trading account
> interest String Interest to be deducted
Only applicable to Market loans
> posLoan String Frozen amount for current account (Within the locked quota)
Only applicable to VIP loans
> availLoan String Available amount for current account (Within the locked quota)
Only applicable to VIP loans
> usedLoan String Borrowed amount for current account
Only applicable to VIP loans
> avgRate String Average interest of already borrowed coin
only applicable to VIP loans

Position builder

Calculates portfolio margin information for simulated position or current position of the user.
You can add up to 200 simulated positions in one request.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/simulated_margin

Request Example

POST /api/v5/account/simulated_margin
body
{
   "instType":"SWAP",
   "inclRealPos":true,
   "simPos":[
     {
          "pos":"10",
          "instId":"BTC-USDT-SWAP"
     },
     {
          "pos":"10",
          "instId":"LTC-USDT-SWAP"
     }
   ]
}

Only existing real positions are calculated
POST /api/v5/account/simulated_margin
body
{
   "inclRealPos":true
}


Only virtual positions are calculated
POST /api/v5/account/simulated_margin
body
{
   "inclRealPos":"false",
   "simPos":[
     {
          "pos":"10",
          "instId":"BTC-USDT-SWAP"
     },
     {
          "pos":"10",
          "instId":"LTC-USDT-SWAP"
     }
   ]
}

Request Parameters

Parameter Type Required Description
instType String No Instrument type
SWAP
FUTURES
OPTION
inclRealPos Boolean No Whether import existing positions
true：Import existing positions and hedge with simulated ones
false：Only use simulated positions
The default is true
spotOffsetType String No Spot-derivatives risk offset mode
1: Spot-derivatives (USDT) 2: Spot-derivatives (crypto) 3: Derivatives-only
The default is 3
simPos Array No List of positions
> instId String No Instrument ID
> pos String No Quantity of positions

Response Example

{
    "code": "0",
    "data": [
        {
            "imr": "0.005432310199023",
            "mmr": "0.0041787001530946",
            "mr1": "0.0041787001530946",
            "mr2": "0.0000734347499275",
            "mr3": "0",
            "mr4": "0",
            "mr5": "0",
            "mr6": "0.0028031968471",
            "mr7": "0.0022",
            "posData": [
                {
                    "delta": "-0.008926024905498",
                    "gamma": "-0.0707804093543001",
                    "instId": "BTC-USD-220325-50000-C",
                    "instType": "OPTION",
                    "notionalUsd": "3782.9800000000005",
                    "pos": "-1",
                    "theta": "0.000093015207115",
                    "vega": "-0.0000382697346669"
                }
            ],
            "riskUnit": "BTC-USD",
            "ts": "1646639497536"
        },
        {
            "acctImr": "6847.294720745276",
            "acctMmr": "5140.116514138115"
        }
    ],
    "msg": ""
}
Response Parameters
Parameters Types Description
riskUnit String risk unit
ts String Unix timestamp format in milliseconds, e.g.1597026383085
mmr String Maintenance margin requirement of riskUnit dimension
imr String Initial margin requirement of riskUnit dimension
mr1 String spot & vol movements
mr2 String theta decay
mr3 String vega term-structure
mr4 String basis risk
mr5 String interest-rate risk
mr6 String extreme market move
mr7 String transaction cost & slippage
acctImr String Initial margin requirement of account dimension
acctMmr String Maintenance margin requirement of account dimension
posData Array List of positions
> instId String Instrument ID, e.g. BTC-USD-180216
> instType String Instrument type
> pos String Quantity of positions
> notionalUsd String Notional value of positions in USD
> delta String Sensitivity of option price to uly price
> gamma String The delta is sensitivity to uly price
> vega String Sensitivity of option price to implied volatility
> theta String Sensitivity of option price to remaining maturity

Get Greeks

Retrieve a greeks list of all assets in the account.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Requests

GET /api/v5/account/greeks

Request Example

Get the greeks of all assets in the account
GET /api/v5/account/greeks

Get the greeks of BTC assets in the account
GET /api/v5/account/greeks?ccy=BTC
Request Parameters
Parameters Types Required Description
ccy String No Single currency, e.g. BTC.

Response Example

{
    "code":"0",
    "data":[
        {            
           "thetaBS": "",
           "thetaPA":"",
           "deltaBS":"",
           "deltaPA":"",
           "gammaBS":"",
           "gammaPA":"",
           "vegaBS":"",    
           "vegaPA":"",
           "ccy":"BTC",
           "ts":"1620282889345"
        }
    ],
    "msg":""
}
Response Parameters
Parameters Types Description
deltaBS String delta：Black-Scholes Greeks in dollars
deltaPA String delta：Greeks in coins
gammaBS String gamma：Black-Scholes Greeks in dollars,only applicable to OPTION
gammaPA String gamma：Greeks in coins,only applicable to OPTION
thetaBS String theta：Black-Scholes Greeks in dollars,only applicable to OPTION
thetaPA String theta：Greeks in coins,only applicable to OPTION
vegaBS String vega：Black-Scholes Greeks in dollars,only applicable to OPTION
vegaPA String vega：Greeks in coins,only applicable to OPTION
ccy String Currency
ts String Time of getting Greeks, Unix timestamp format in milliseconds, e.g. 1597026383085

Get PM position limitation

Retrieve cross position limitation of SWAP/FUTURES/OPTION under Portfolio margin mode.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/account/position-tiers

Request Example

Query limitation of BTC-USDT
GET /api/v5/account/position-tiers?instType=SWAP&uly=BTC-USDT
Request Parameters
Parameter Type Required Description
instType String Yes Instrument type
SWAP
FUTURES
OPTION
uly String Conditional Single underlying or multiple underlyings (no more than 3) separated with comma.
Either uly or instFamily is required. If both are passed, instFamily will be used.
instFamily String Conditional Single instrument family or instrument families (no more than 5) separated with comma.
Either uly or instFamily is required. If both are passed, instFamily will be used.

Response Example

{
  "code": "0",
  "data": [
    {
      "instFamily": "BTC-USDT",
      "maxSz": "10000",
      "posType": "",
      "uly": "BTC-USDT"
    }
  ],
  "msg": ""
}
Response Parameters
Parameter Type Description
uly String Underlying
Applicable to FUTURES/SWAP/OPTION
instFamily String Instrument family
Applicable to FUTURES/SWAP/OPTION
maxSz String Max number of positions
posType String Limitation of position type, only applicable to cross OPTION under portfolio margin mode
1: Contracts of pending orders and open positions for all derivatives instruments. 2: Contracts of pending orders for all derivatives instruments. 3: Pending orders for all derivatives instruments. 4: Contracts of pending orders and open positions for all derivatives instruments on the same side. 5: Pending orders for one derivatives instrument. 6: Contracts of pending orders and open positions for one derivatives instrument. 7: Contracts of one pending order.

Set risk offset type

Configure the risk offset type in portfolio margin mode.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-riskOffset-type

Request Example

POST /api/v5/account/set-riskOffset-type
body 
{
    "type":"1"
}

Request Parameters

Parameter Type Required Description
type String Yes Risk offset type
1: Spot-derivatives (USDT) risk offset
2: Spot-derivatives (Crypto) risk offset
3:Derivatives only mode

Response Example

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

Response Parameters

Parameter Type Description
type String Risk offset type
1: Spot-derivatives (USDT) risk offset
2: Spot-derivatives (Crypto) risk offset
3:Derivatives only mode

Activate option

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/activate-option

Request Parameters

None

Response Example

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

Response Parameters

Parameter Type Description
ts String Activation time

Set auto loan

Only applicalbe to Multi-currency margin and Portfolio margin

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

POST /api/v5/account/set-auto-loan

Request Example

POST /api/v5/account/set-auto-loan
body
{
    "autoLoan":true,
}

Request Parameters

Parameter Type Required Description
autoLoan Boolean No Whether to automatically make loans
Valid values are true, false
The default is true

Response Example

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

Response Parameters

Parameter Type Description
autoLoan Boolean Whether to automatically make loans

SubAccount

The API endpoints of SubAccount require authentication.

View sub-account list

Applies to master accounts only

Rate limit：2 requests per 2 seconds

Rate limit rule: UserID

HTTP request

GET /api/v5/users/subaccount/list

Request sample

GET /api/v5/users/subaccount/list

Request parameters

Parameter Type Required Description
enable String No Sub-account status
true: Normal false: Frozen
subAcct String No Sub-account name
after String No If you query the data prior to the requested creation time ID, the value will be a Unix timestamp in millisecond format.
before String No If you query the data after the requested creation time ID, the value will be a Unix timestamp in millisecond format.
limit String No Number of results per request. The maximum is 100. The default is 100.

Returned results

{
    "code":"0",
    "msg":"",
    "data":[
                   {
                      "enable":true,
                      "subAcct":"test-1",
                      "type":"1",
                      "label":"trade futures",
                      "mobile":"1818181",
                      "gAuth":true,
                      "canTransOut": true,
                      "ts":"1597026383085"
                   },
                   {
                      "enable":false,
                      "type":"1",
                      "subAcct":"test-2",
                      "label":"trade spot",
                      "mobile":"1818199",
                      "gAuth":true,
                      "canTransOut": false,
                      "ts":"1597026383082"
                   }

    ]
}

Response parameters

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

Reset the API Key of a sub-account

Applies to master accounts only and master accounts API Key must be linked to IP addresses.

Rate limit：1 request per second

Rate limit rule: UserID

HTTP request

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

Request sample

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

Request parameters

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

Returned results

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

Response parameters

Parameter name Type Description
subAcct