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
- Learn how to trade with V5 API: A complete guide to OKX’s API v5 upgrade
- Learn python spot trading step by step: Python Spot Trading Tutorial
- Learn python derivatives trading step by step: Python Derivatives Trading Tutorial
- Use Python SDK for easier integration: Python SDK
- Get help in our Discord group: OKX Official Discord Channel
- Get support in our Telegram group: OKX API
- Subscribe to API related changes: OKX API Announcement
- Please take 1 minute to help us improve: V5 API Satisfaction Survey
- If you have any questions, please consult online customer service
V5 API Key Creation
Please refer to my api page regarding V5 API Key creation.
Production Trading Services
The Production Trading URL:
- REST:
https://www.okx.com/
- Public WebSocket:
wss://ws.okx.com:8443/ws/v5/public
- Private WebSocket:
wss://ws.okx.com:8443/ws/v5/private
- For certain channels:
wss://ws.okx.com:8443/ws/v5/business
AWS URL:
- REST:
https://aws.okx.com
- Public WebSocket:
wss://wsaws.okx.com:8443/ws/v5/public
- Private WebSocket:
wss://wsaws.okx.com:8443/ws/v5/private
- For certain channels:
wss://wsaws.okx.com:8443/ws/v5/business
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:
- REST:
https://www.okx.com
- Public WebSocket:
wss://wspap.okx.com:8443/ws/v5/public?brokerId=9999
- Private WebSocket:
wss://wspap.okx.com:8443/ws/v5/private?brokerId=9999
- For certain channels:
wss://wspap.okx.com:8443/ws/v5/business?brokerId=9999
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 maximum number of pending orders (including post only orders, limit orders and taker orders that are being processed): 4,000
The maximum number of pending algo orders:
- TP/SL order: 100 per instrument
- Trigger order: 500
- Trailing order: 50
- Iceberg order: 100
- TWAP order: 20
The rules for the returning data are as follows:
code
andmsg
represent the request result or error reason when the return data hascode
, and has notsCode
;It is
sCode
andsMsg
that represent the request result or error reason when the return data hassCode
rather thancode
andmsg
.
The introduction of instFamily
:
- There are no difference between
uly
andinstFamily
:- For BTC-USD-SWAP,
uly
andinstFamily
are both BTC-USD. For BTC-USDC-SWAP,uly
andinstFamily
are both BTC-USDC. - If you set the request parameter "uly" as BTC-USD, you will get the data for BTC-USD (coin-margined) contracts.
- If you set the request parameter "instFamily" as BTC-USD, then you also will get data for BTC-USD (coin-margined) contracts. -You can look up the corresponding instFamily of each instrument from the "Get instruments" endpoint.
- For BTC-USD-SWAP,
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:
WebSocket login and subscription rate limits are based on IP address.
Public unauthenticated REST rate limits are based on IP address.
Private REST rate limits are based on User ID (sub-accounts have individual User IDs).
WebSocket order management rate limits are based on User ID (sub-accounts have individual User IDs).
Trading-related APIs
For Trading-related APIs (place order, cancel order, and amend order) the following conditions apply:
Rate limits are shared across the REST and WebSocket channels.
Rate limits for placing orders, amending orders, and cancelling orders are independent from each other.
Rate limits are defined on the Instrument ID level (except Options)
Rate limits for Options are defined based on the Instrument Family level. Refer to the Get instruments endpoint to view Instrument Family information.
Rate limits for a multiple order endpoint and a single order endpoint are also independent, with the exception being when there is only one order sent to a multiple order endpoint, the order will be counted as a single order and adopt the single order rate limit.
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):
- VIP 2 or above on fee schedule
- Qualified Market Maker on other exchange
Interested parties could drop us an email at [email protected]
with the below details:
- Your account email
- Contact details (additional to your account email)
- A screenshot of your maker trading volume (such as 30 days trading volume or VIP status)
- Specify the product line you would like to provide liquidity for (you may choose more than one)
- Spot
- Futures
- Perpetual Swap
- Spot
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.
Clicking
Try it out
button in Parameters Panel and editing request parameters.Clicking
Execute
button to send your request. You can check response in Responses panel.
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
- 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.
- Quotes - Quotes are created by the Maker in response to a requested RFQ.
- 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.
- Taker creates an RFQ and selects which counterparties to broadcast the RFQ to.
- Multiple Maker(s) send a two way quote as a response to the RFQ.
- Taker chooses to execute upon the best quote and the trade is sent to OKX for clearing & settlement.
- Taker & Maker receive confirmation of the trade's execution.
- Trade economics are published to market feed. (minus counterparty info)
Taker's Perspective
- Taker creates an RFQ using
POST /api/v5/rfq/create-rfq
. Taker can pull available instruments viaGET /api/v5/public/instruments
and available counterparties fromGET /api/v5/rfq/counterparties
. - Taker can cancel an RFQ anytime until it becomes inactive with
POST /api/v5/rfq/cancel-rfq
. - Maker, who is a requested counterparty to the RFQ, and is notified over the
rfqs
WebSocket channel, can provide a Quote to the RFQ. - Taker, who will be notified of quotes from the
quotes
WebSocket channel, can execute upon the best Quote withPOST /api/v5/rfq/execute-quote
. - Taker will receive confirmation of the trade's successful execution on the
struc-block-trades
andrfqs
WebSocket channel. - 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
- Maker is notified about a new RFQ who they are a couterparty to, on the
rfqs
WebSocket channel. - Maker can create a one way or two way Quote using
POST /api/v5/rfq/create-quote
. - Maker can cancel an existing quote anytime until it becomes inactive with
POST /api/v5/rfq/cancel-quote
. - Taker chooses to execute upon an available Quote.
- Maker will receive updates of their Quote from the
quotes
WebSocket channel. - Maker will receive confirmation of the successful execution of their Quote from the
struc-block-trades
andquotes
WebSocket channel. - 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:
- APIKey
- SecretKey
- Passphrase
The system returns randomly-generated APIKeys and SecretKeys. You will need to provide the Passphrase to access the API. We store the salted hash of your Passphrase for authentication. We cannot recover the Passphrase if you have lost it. You will need to create a new set of APIKey.
There are three permissions below that can be associated with an API key. One or more permission can be assigned to any key.
- Read - Can request and view account info such as bills and order history.
- Withdraw - Can initiate withdrawals, and request and view account info such as bills and history.
- Trade - Can place and cancel orders, and request and view account info such as bills and history.
Making Requests
All private REST requests must contain the following headers:
OK-ACCESS-KEY
The API Key as a String.OK-ACCESS-SIGN
The Base64-encoded signature (see Signing Messages subsection for details).OK-ACCESS-TIMESTAMP
The UTC timestamp of your request .e.g : 2020-12-08T09:08:57.715ZOK-ACCESS-PASSPHRASE
The passphrase you specified when creating the APIKey.
Request bodies should have content type application/json
and be in valid JSON format.
Signature
Signing Messages
The OK-ACCESS-SIGN
header is generated as follows:
- Create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation).
- Prepare the SecretKey.
- Sign the prehash string with the SecretKey using the HMAC SHA256.
- Encode the signature in the Base64 format.
Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))
The timestamp
value is the same as the OK-ACCESS-TIMESTAMP
header with millisecond ISO format, e.g. 2020-12-08T09:08:57.715Z
.
The request method should be in UPPERCASE: e.g. GET
and POST
.
The requestPath
is the path of requesting an endpoint.
Example: /api/v5/account/balance
The body
refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET
requests).
Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
The SecretKey is generated when you create an APIKey.
Example: 22582BD0CFF14C41EDBF1AB98506286D
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 modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
ordType | String | Yes | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 OrdersDefault 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 typelast : last price index : index price mark : mark price The Default is last |
slTriggerPxType | String | No | Stop-loss trigger price typelast : 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 modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
ordType | String | Yes | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 OrdersDefault 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 typelast : last price index : index price mark : mark price The Default is last |
slTriggerPxType | String | No | Stop-loss trigger price typelast : 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 typelast : last price index : index price mark : mark price |
newSlTriggerPxType | String | Conditional | Stop-loss trigger price typelast : 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 failsfalse 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 | 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 typelast : last price index : index price mark : mark price |
newSlTriggerPxType | Conditional | No | Stop-loss trigger price typelast : 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 modecross 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 typeSPOT 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 OrdersDefault 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 typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : 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 | Categorynormal 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 marginmanual , 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 typeSPOT 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 typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc : Market order with immediate-or-cancel order |
state | String | No | Statelive 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 OrdersDefault 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 typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 | Statelive 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : 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 marginmanual , 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 typeSPOT 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 typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc : Market order with immediate-or-cancel order |
state | String | No | Statecanceled 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 OrdersDefault 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 typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : 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 typeSPOT 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 typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc : Market order with immediate-or-cancel order |
state | String | No | Statecanceled 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 OrdersDefault 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 typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : 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 typeSPOT 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 sidelong short it returns net innet mode. |
execType | String | Liquidity taker or maker, T : taker M : makerNot 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 typeSPOT 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 sidelong short it returns net innet mode. |
execType | String | Liquidity taker or maker, T : taker M : makerNot 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 ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : 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 orderDefault 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 typelast : last priceindex : index pricemark : mark priceThe 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 typelast : last priceindex : index pricemark : mark priceThe 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 typelast : last priceindex : index pricemark : mark priceThe 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 typelast : last price index : index price mark : mark price |
newSlTriggerPxType | String | Conditional | Stop-loss trigger price typelast : 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 OrdersDefault 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
triggerPx | String | trigger price. |
triggerPxType | String | trigger price type. last : last priceindex : index pricemark : 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 marginmanual , 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 ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : 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 typeSPOT 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price |
slTriggerPx | String | Stop-loss trigger price |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price |
triggerPx | String | Trigger price |
triggerPxType | String | Trigger price type. last : last priceindex : index pricemark : mark price |
ordPx | String | Order price |
actualSz | String | Actual order quantity |
tag | String | Order tag |
actualPx | String | Actual order price |
actualSide | String | Actual trigger sidetp : 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 marginmanual , 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 ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : TWAP order |
state | String | Conditional | Stateeffective canceled order_failed Either state or algoId is requied |
algoId | String | Conditional | Algo ID Either state or algoId is required. |
instType | String | No | Instrument typeSPOT 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 OrdersDefault 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 priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
triggerPx | String | trigger price. |
triggerPxType | String | trigger price type. last : last priceindex : index pricemark : 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 marginmanual , 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 account6 : Funding account, 18 : Trading account |
to | String | Yes | The beneficiary account6 : 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 type0 : transfer within account1 : 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 type0 : transfer within account1 : 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 type0 : transfer within account1 : 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 account6 : Funding account 18 : Trading account |
to | String | The beneficiary account6 : Funding account 18 : Trading account |
subAcct | String | Name of the sub-account |
instId | String | deprecated |
toInstId | String | deprecated |
state | String | Transfer statesuccess , 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 type1 : Deposit2 : Withdrawal13 : Canceled withdrawal20 : 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 Airdrop47 : System reversal48 : Event Reward49 : Event Giveaway50 : Received from appointments51 : Deducted from appointments52 : Red packet sent53 : Red packet snatched54 : Red packet refunded61 : Conversion68 : Claim rebate card69 : Distribute rebate card72 : Token received73 : Token given away74 : Token refunded75 : Subscription to savings76 : Redemption to savings77 : Distribute78 : Lock up79 : Node voting80 : Staking81 : Vote redemption82 : Staking redemption83 : Staking yield84 : Violation fee85 : PoW mining yield86 : Cloud mining pay87 : Cloud mining yield88 : Subsidy89 : Staking90 : Staking subscription91 : staking redemption92 : Add collateral93 : Redeem collateral94 : Investment95 : Borrower borrows96 : Principal transferred in97 : Borrower transferred loan out98 : Borrower transferred interest out99 : Investor transferred interest in102 : Prepayment penalty transferred in103 : Prepayment penalty transferred out104 : Mortgage fee transferred in105 : Mortgage fee transferred out106 : Overdue fee transferred in107 : Overdue fee transferred out108 : Overdue interest transferred out109 : Overdue interest transferred in110 : Collateral for closed position transferred in111 : Collateral for closed position transferred out112 : Collateral for liquidation transferred in113 : Collateral for liquidation transferred out114 : Insurance fund transferred in115 : Insurance fund transferred out 116 : Place an order117 : Fulfill an order118 : Cancel an order119 : Merchants unlock deposit120 : Merchants add deposit121 : FiatGateway Place an order122 : FiatGateway Cancel an order123 : FiatGateway Fulfill an order124 : Jumpstart unlocking125 : Manual deposit126 : Interest deposit127 : Investment fee transferred in128 : Investment fee transferred out129 : Rewards transferred in130 : Transferred from Trading account131 : Transferred to Trading account132 : Frozen by customer service133 : Unfrozen by customer service134 : Transferred by customer service135 : Cross chain exchange136 : Convert137 : ETH 2.0 Subscription138 : ETH 2.0 Swapping139 : ETH 2.0 Earnings143 : System Reverse144 : Transfer out of unified account reserve145 : Reward Expired146 : Customer feedback147 : vested sushi rewards150 : Affiliate commission151 : Referral reward152 : Broker reward153 : Joiner reward154 : Mystery box reward155 : Rewards withdraw156 : Fee rebate157 : Collected crypto160 : Dual Investment subscribe161 : Dual Investment collection162 : Dual Investment profit163 : Dual Investment refund169 : 2022 new year rewards172 : Sub-affiliate commission173 : Fee rebate174 : Pay175 : Locked collateral176 : Loan177 : Added collateral178 : Returned collateral179 : Repayment180 : Unlocked collateral181 : Airdrop Payment182 : Feedback bounty183 : Invite friends rewards184 : Divide the reward pool185 : Broker Convert Reward186 : FreeETH187 : Convert transfer188 : Slot Auction Conversion189 : Mystery box bonus193 : Card payment Buy195 : Untradable asset withdrawal196 : Untradable asset withdrawal revoked197 : Untradable asset deposit198 : Untradable asset collection reduce199 : Untradable asset collection increase200 : Buy202 : Price Lock Subscribe203 : Price Lock Collection204 : Price Lock Profit205 : Price Lock Refund207 : Dual Investment Lite Subscribe208 : Dual Investment Lite Collection209 : Dual Investment Lite Profit210 : Dual Investment Lite Refund211 : Win crypto with Satoshi212 : Multi-collateral loan collateral locked213 : Collateral transfered out from user account214 : Collateral returned to users215 : Multi-collateral loan collateral released216 : Loan transferred to user's account217 : Multi-collateral loan borrowed218 : Multi-collateral loan repaid219 : Repayment transferred from user's account220 : Delisted crypto221 : Blockchain's withdrawal fee222 : Withdrawal fee refund223 : Copy trading profit share224 : Service fee225 : Shark Fin subscribe226 : Shark Fin collection227 : Shark Fin profit228 : Shark Fin refund229 : Airdrop230 : Token migration completed232 : Subsidized interest received233 : Broker rebate compensation263 : Strategy bots profit share270 : DCD broker transfer271 : DCD broker rebate284 : Transfer out trading sub-account285 : Transfer in trading sub-account286 : Transfer out custody funding account287 : Transfer in custody funding account288 : 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 Type3 : internal transfer4 : deposit from chain |
state | String | No | Status of deposit 0 : waiting for confirmation1 : deposit credited 2 : deposit successful 8 : pending due to temporary deposit suspension on this crypto currency11 : match the address blacklist12 : account or deposit is frozen13 : sub-account deposit interception14 : 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 confirmation1 : deposit credited 2 : deposit successful 8 : pending due to temporary deposit suspension on this crypto currency11 : match the address blacklist12 : account or deposit is frozen13 : sub-account deposit interception14 : 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 method3 : 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 transfer4 : 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 nottrue : 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 statefullyFilled : 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 statefullyFilled : 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 typeMARGIN 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 modecross isolated |
posId | String | Position ID |
posSide | String | Position sidelong , 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 priceindex :index pricemark :mark price |
> tpTriggerPx | String | Take-profit trigger price. |
> tpTriggerPxType | String | Take-profit trigger price type. last :last priceindex :index pricemark :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 typeMARGIN SWAP FUTURES OPTION |
instId | String | No | Instrument ID, e.g. BTC-USD-SWAP |
mgnMode | String | No | Margin modecross isolated |
type | String | No | The type of closing position1 :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 modecross isolated |
type | String | The type of closing position1 :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 modecross 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 sidelong 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 typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Bill currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : 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 subtype1 : 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 modeisolated 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 account6 : FUNDING 18 : Trading accountOnly applicable to transfer . When bill type is not transfer , the field returns "". |
to | String | The beneficiary account6 : FUNDING 18 : Trading accountOnly 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 typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Bill currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : 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 subtype1 : 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 modeisolated 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 account6 : FUNDING 18 : Trading accountOnly applicable to transfer . When bill type is not transfer , the field returns "". |
to | String | The beneficiary account6 : FUNDING 18 : Trading accountOnly 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 modelong_short_mode : long/short, only applicable to FUTURES/SWAP net_mode : net |
autoLoan | Boolean | Whether to borrow coins automaticallytrue : borrow coins automatically false : not borrow coins automatically |
greeksType | String | Current display type of GreeksPA : 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 settingsautomatic : Auto transfers autonomy : Manual transfers |
mgnIsoMode | String | Margin isolated margin trading settingsautomatic : 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 type1 : Spot-Derivatives(USDT) to be offsetted2 : Spot-Derivatives(Coin) to be offsetted3 : Only derivatives to be offsettedOnly 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 activated0 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 modelong_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 modeisolated cross Can only be cross if ccy is passed. |
posSide | String | Conditional | Position sidelong 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 modecross 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 modecross 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 offsetDefault 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 buyThe 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 sellThe 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 modecross 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 offsetDefault 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 marginreduce : 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 modecross 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 sidelong 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 modeisolated 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 sidebuy 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 typeSPOT 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 type1 : VIP loans2 : Market loansDefault is Market loans |
ccy | String | No | Loan currency, e.g. BTC Only applicable to Market loans Only applicable to MARGIN |
instId | String | No | Instrument ID, e.g. BTC-USDT Only applicable to Market loans |
mgnMode | String | No | Margin modecross 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 type1 : VIP loans2 : 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 modecross 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 coinsBS : 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 typeMARGIN 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 | Type1 : borrow2 : repay3 : 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 to MARGIN |
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 to MARGIN |
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 | State1 :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 type1 : VIP loans2 : Market loansDefault 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 typeSWAP FUTURES OPTION |
inclRealPos | Boolean | No | Whether import existing positionstrue :Import existing positions and hedge with simulated ones false :Only use simulated positionsThe 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 typeSWAP 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 type1 : Spot-derivatives (USDT) risk offset2 : Spot-derivatives (Crypto) risk offset3 :Derivatives only mode |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"type": "1"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
type | String | Risk offset type1 : Spot-derivatives (USDT) risk offset2 : Spot-derivatives (Crypto) risk offset3 :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 : TradeSeparate 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 |