Introduction
Wootrade. A privately-accessible liquidity venue for the trading of cryptocurrencies.
Wootrade provides clients an easily accessible deep pool of liquidity sourced from the largest exchanges and from Kronos’ HFT proprietary trading. We utilize advanced crossing and routing methods which provides ease of access and superior trade execution to select exchanges.
We provide two interfaces to communicate between Wootrade and clients.
- RESTful API interface: Provides sending events like create order, cancel order, fetch balance, ...etc.
- Websocket interface V2: Provides real-time orderbook data feed and order update feed.
Base endpoints:
https://api.woo.org/
(Production)
Authorization:
All our interfaces required key to access, and the token will be pre-generated by us.
Please set corrsponded header in your request. See refer to Authenticaton for more information.
Symbol:
Wootrade use the format of <TYPE>_<BASE>_<QUOTE>
to represent a symbol name, for example: SPOT_BTC_USDT
means that it is BTC_USDT
pair in SPOT
trading market.
Rate Limit:
Rate limit is counted using api key, and if your application reached the rate limit of certain endpoint, the server will return an error result with http code 429
. You may need wait until next time horizon.
Error Message:
Errors consist of three parts: an error code, detail message and a success flag.
{
"success": false,
"code": -1005, // Error code
"message": "order_price must be a positive number" // Detail message
}
All API will return following json when api failed, the "message" will contain the detail error message, it may because some data are in wrong format, or other type of error.
Specific error codes and messages are defined in Errors Codes.
Authentication
Client need to ask for an api_key
and api_secret
, and use these to sign your request.
Example
Here we provide a simple example that shows you how to send a valid request to WooTrade.
Assume following infomation:
Key | Value | Description |
---|---|---|
api_key |
AbmyVJGUpN064ks5ELjLfA== |
create from WOO X console |
api_secret |
QHKRXHPAW1MC9YGZMAT8YDJG2HPR |
create from WOO X console |
timestamp |
1578565539808 |
Unix epoch time in milliseconds |
Hash you request parameters with api_secret
, the hashing logic is described as following:
If the request looks like:
POST /v1/order
# Body parameter:
symbol:SPOT_BTC_USDT
order_type:LIMIT
order_price:9000
order_quantity:0.11
side:BUY
Steps to normalize request content:
- use query string as the parameters for GET methods and body parameters for POST and DELETE methods.
- concat query string and body parameters with alphabet order in query string format.
- concat
timestamp
with above result, using|
as seperator.
Normalize request content, The result content would look like following
order_price=9000&order_quantity=0.11&order_type=LIMIT&side=BUY&symbol=SPOT_BTC_USDT|1578565539808
Then use
api_secret
to hash it with HMACSHA256
algorithm, you can useopenssl
to get this:
$ echo -n "order_price=9000&order_quantity=0.11&order_type=LIMIT&side=BUY&symbol=SPOT_BTC_USDT|1578565539808" | openssl dgst -sha256 -hmac "QHKRXHPAW1MC9YGZMAT8YDJG2HPR"
(stdin)= 20da0852f73b20da0208c7e627975a59ff072379883d8457d03104651032033d
Put the HMAC signature in request header x-api-signature
, and put timestamp in x-api-timestamp
, and also api key in x-api-key
.
So the final request would look like:
Security
There have three layer checker to check if a request is valid. WooTrade server only accept the request that passed all checker. The checker is defined as following:
Revoken checker:
The api key/secret can be revoke manaually by clients' request. if the key has been revoken, all access token generated by this key cannot be use.
Request IP checker:
The api key/secret can be tie to specific ips (default is empty). if the request is not come from allowed ip addresses, the request would be reject.
Request Timestamp checker:
The request would be considered expired and get rejected if the timestamp in x-api-timestamp
header have 300+ seconds difference from the API server time.
HMAC Parameter Signature:
The request must have a x-api-signature
header that is generate from request parameters and signed with your secret key.
Error Codes
Errors consist of three parts: an error code and a message. Codes are universal, but messages can vary. Here is the error JSON payload:
{
"success": false,
"code": -1001, // Error code
"message": "order_price must be a positive number" // Detail message
}
Error Code | Status Code | Error Name | Description |
---|---|---|---|
-1000 |
500 | UNKNOWN |
An unknown error occurred while processing the request. |
-1001 |
401 | INVALID_SIGNATURE |
The api key or secret is in wrong format. |
-1002 |
401 | UNAUTHORIZED |
API key or secret is invalid, it may because key have insufficient permission or the key is expired/revoked. |
-1003 |
429 | TOO_MANY_REQUEST |
Rate limit exceed. |
-1004 |
400 | UNKNOWN_PARAM |
An unknown parameter was sent. |
-1005 |
400 | INVALID_PARAM |
Some parameters are in wrong format for api. |
-1006 |
400 | RESOURCE_NOT_FOUND |
The data is not found in server. For example, when client try canceling a CANCELLED order, will raise this error. |
-1007 |
409 | DUPLICATE_REQUEST |
The data is already exists or your request is duplicated. |
-1008 |
400 | QUANTITY_TOO_HIGH |
The quantity of settlement is too high than you can request. |
-1009 |
400 | CAN_NOT_WITHDRAWAL |
Can not request withdrawal settlement, you need to deposit other arrears first. |
-1011 |
400 | RPC_NOT_CONNECT |
Can not place/cancel orders, it may because internal network error. Please try again in a few seconds. |
-1012 |
400 | RPC_REJECT |
The place/cancel order request is rejected by internal module, it may because the account is in liquidation or other internal errors. Please try again in a few seconds. |
-1101 |
400 | RISK_TOO_HIGH |
The risk exposure for client is too high, it may cause by sending too big order or the leverage is too low. please refer to client info to check the current exposure. |
-1102 |
400 | MIN_NOTIONAL |
The order value (price * size) is too small. |
-1103 |
400 | PRICE_FILTER |
The order price is not following the tick size rule for the symbol. |
-1104 |
400 | SIZE_FILTER |
The order quantity is not following the step size rule for the symbol. |
-1105 |
400 | PERCENTAGE_FILTER |
Price is X% too high or X% too low from the mid price. |
RESTful API
Exchange Information
Limit: 10 requests per 1 second per IP address
GET /v1/public/info/:symbol
Get send order requirement by symbol, there have some rules need to fullfill in order to successfully send order, which is defined as following:
Price filter
price
>=quote_min
price
<=quote_max
(price - quote_min) % quote_tick
should equal to zeroprice
<=asks[0].price * (1 + price_range)
when BUYprice
>=bids[0].price * (1 - price_range)
when SELL
Size filter
base_min
<=quantity
<=base_max
(quantity - base_min) % base_tick
should equal to zero
Min Notional filter
price * quantity
should greater thanmin_notional
Risk Exposure filer
- For margin trading, margin rate should exceed certain threshold as per leverage. For spot trading, order size should be within holding threshold. See account_info
Response
{
"success": true,
"info": {
"symbol": "SPOT_BTC_USDT",
"quote_min": 100,
"quote_max": 100000,
"quote_tick": 0.01,
"base_min": 0.0001,
"base_max": 20,
"base_tick": 0.0001,
"min_notional": 0.02,
"price_range": 0.5,
"created_time": "1575014248.99", // Unix epoch time in seconds
"updated_time": "1575014248.99", // Unix epoch time in seconds
}
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y |
Available Symbols (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/info
Get available symbols that WooTrade supported, and also send order rules for each symbol. The definition of rules can be found at Exchange Infomation
Response
{
"success": true,
"rows": [
{
"created_time": "1575441595.65", // Unix epoch time in seconds
"updated_time": "1575441595.65", // Unix epoch time in seconds
"symbol": "SPOT_BTC_USDT",
"quote_min": 100,
"quote_max": 100000,
"quote_tick": 0.01,
"base_min": 0.0001,
"base_max": 20,
"base_tick": 0.0001,
"min_notional": 0.02,
"price_range": 0.99
},
// ...
]
}
Parameters
None
Market Trades (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/market_trades
Get latest market trades.
Response
{
"success": true,
"rows": [
{
"symbol": "SPOT_ETH_USDT",
"side": "BUY",
"executed_price": 202,
"executed_quantity": 0.00025,
"executed_timestamp": "1567411795.000000" // Unix epoch time in seconds
}
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y | |
limit | number | N (default: 10) | Numbers of trades want to query. |
Available Token (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/token
Get available tokens that WooTrade supported, it need to use when you call get deposit address or withdraw api.
Response
{
"success": true,
"rows": [
{
"created_time": "1579399877.02", // Unix epoch time in seconds
"updated_time": "1579399877.02", // Unix epoch time in seconds
"token": "BTC",
"balance_token": "BTC",
"fullname": "Bitcoin",
"decimals": 8
},
{
"created_time": "1579399877.02",
"updated_time": "1579399877.02",
"token": "BTC_USDT",
"balance_token": "USDT",
"fullname": "Tether",
"decimals": 8
},
{
"created_time": "1579399877.02",
"updated_time": "1579399877.02",
"token": "ETH",
"balance_token": "ETH",
"fullname": "Ethereum",
"decimals": 18
},
{
"created_time": "1579399877.02",
"updated_time": "1579399877.02",
"token": "ETH_OKB",
"balance_token": "OKB",
"fullname": "OKB",
"decimals": 18
}
]
}
Parameters
None
Token Network (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/token_network
Get the available networks for each token as well as the deposit/withdrawal information.
Response
{
"success": true,
"rows": [
{
"protocol": "BTC",
"token": "BTC",
"name": "Bitcoin",
"minimum_withdrawal": 0.01,
"withdrawal_fee": 0.05,
"allow_deposit": 1,
"allow_withdraw": 1
},
{
"protocol": "ERC20",
"token": "ETH",
"name": "Ethereum",
"minimum_withdrawal": 0.03,
"withdrawal_fee": 0.06,
"allow_deposit": 1,
"allow_withdraw": 1
},
{
"protocol": "ERC20",
"token": "WOO",
"name": "Ethereum",
"minimum_withdrawal": 30,
"withdrawal_fee": 20,
"allow_deposit": 1,
"allow_withdraw": 1
},
{
"protocol": "BEP20",
"token": "WOO",
"name": "Binance Smart Chain",
"minimum_withdrawal": 30,
"withdrawal_fee": 3,
"allow_deposit": 1,
"allow_withdraw": 1
},
// ...
]
}
Parameters
None
Get Predicted Funding Rate for All Markets (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/funding_rates
Get predicted funding rate and the latest funding rate for all the markets.
Response
{
"success": true,
"rows": [
{
"symbol": "PERP_BTC_USDT",
"est_funding_rate": 0.12345689,
"est_funding_rate_timestamp": 1636388220001,
"last_funding_rate": 0.12345689,
"last_funding_rate_timestamp": 1567411795000, // use rate to end calculating funding fee time
"next_funding_time": 1567411995000
},
{
"symbol": "PERP_ETH_USDT",
"est_funding_rate": 0.12345689,
"est_funding_rate_timestamp": 1636388220001,
"last_funding_rate": 0.12345689,
"last_funding_rate_timestamp": 1567411795000, // use rate to end calculating funding fee time
"next_funding_time": 1567411995000
}
],
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Get Predicted Funding Rate for One Market (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/funding_rate/:symbol
Get predicted funding rate and the latest funding rate for one market.
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y |
Response
{
"success": true,
"symbol": "PERP_BTC_USDT",
"est_funding_rate": 0.12345689,
"est_funding_rate_timestamp": 1636388220001,
"last_funding_rate": 0.12345689,
"last_funding_rate_timestamp": 1567411795000, // use rate to end calculating funding fee time
"next_funding_time": 1567411995000
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Get Funding Rate History for One Market (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/funding_rate_history
Get funding rate for one market.
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y | |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. If start_t and end_t are not filled, the newest funding rate will be returned. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. If start_t and end_t are not filled, the newest funding rate will be returned. |
page | number | N (default: 1) | the page wish to query. |
Response
{
"success": true,
"meta": {
"total": 670,
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"symbol": "PERP_BTC_USDT",
"funding_rate": 0.12345689,
"funding_rate_timestamp": 1567411795000, // use rate to end calculating funding fee time
"next_funding_time": 1567411995000
},
{
"symbol": "PERP_BTC_USDT",
"funding_rate": 0.12345689,
"funding_rate_timestamp": "1567411795.000", // use rate to end calculating funding fee time
"next_funding_time": 1567411995000
}
],
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Get Futures Info for All Markets (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/futures
Get basic futures information for all the markets.
Response
{
"success": true,
"rows": [
{
"symbol": "PERP_BTC_USDT",
"index_price": 56727.31344564,
"mark_price": 56727.31344564,
"est_funding_rate": 0.12345689,
"last_funding_rate": 0.12345689,
"next_funding_time": 1567411795000,
"open_interest": 0.12345689,
"24h_open": 0.16112,
"24h_close": 0.32206,
"24h_high": 0.33000,
"24h_low": 0.14251,
"24h_volume": 89040821.98,
"24h_amount": 22493062.21
},
{
"symbol": "PERP_ETH_USDT",
"index_price": 6727.31344564,
"mark_price": 6727.31344564,
"est_funding_rate": 0.12345689,
"last_funding_rate": 0.12345689,
"next_funding_time": 1567411795000,
"open_interest": 0.12345689,
"24h_open": 0.16112,
"24h_close": 0.32206,
"24h_high": 0.33000,
"24h_low": 0.14251,
"24h_volume": 89040821.98,
"24h_amount": 22493062.21
}
],
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Get Futures for One Market (Public)
Limit: 10 requests per 1 second per IP address
GET /v1/public/futures/:symbol
Get basic futures information for one market.
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y |
Response
{
"success": true,
"info":{
"symbol": "PERP_BTC_USDT",
"index_price": 56727.31344564,
"mark_price": 56727.31344564,
"est_funding_rate": 0.12345689,
"last_funding_rate": 0.12345689,
"next_funding_time": 1567411795000,
"open_interest": 0.12345689,
"24h_open": 0.16112,
"24h_close": 0.32206,
"24h_high": 0.33000,
"24h_low": 0.14251,
"24h_volume": 89040821.98,
"24h_amount": 22493062.21
},
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Token Config
Limit: 10 requests per 1 second
GET /v1/client/token
Get the configuration (collateral ratio, margin ratio factor etc) of the token.
Response
{
"success": true,
"rows": [
{
"token": "BTC",
"collateral_ratio": 0.85,
"margin_factor": 2.3e-8,
"futures_margin_factor": 2.3e-8,
"collateral": true, // if the token is now used as collateral
"can_collateral": true, // if the token can be used as collateral
"can_short": true, // if the token supports short selling
"stable": false // if the token is stable coin or not
},
{
"token": "ETH",
"collateral_ratio": 0.85,
"margin_factor": 2.5e-8,
"futures_margin_factor": 2.3e-8,
"collateral": true,
"can_collateral": true,
"can_short": true,
"stable": false
},
{
"token": "ASD",
"collateral_ratio": 1,
"margin_factor": 0,
"futures_margin_factor": 0,
"collateral": false,
"can_collateral": false,
"can_short": false,
"stable": false
}
]
}
Parameters
None
Send Order
Limit: 2 requests per 1 second per symbol
POST /v1/order
Place order maker/taker, the order executed information will be update from websocket stream. will response immediately with an order created message.
MARKET
type order behavior: it matches until all size executed. If the size is too large (larger than whole book) or the matching price exceeds the price limit (refer to price_range
), then the remaining quantity will be cancelled.
IOC
type order behavior: it matches as much as possible at the order_price. If not fully executed, then remaining quantity will be cancelled.
FOK
type order behavior: if the order can be fully executed at the order_price then the order gets fully executed otherwise would be cancelled without any execution.
ASK
type order behavior: the order price is guranteed to be the best ask price of the orderbook if it gets accepted.
BID
type order behavior: the order price is guranteed to be the best bid price of the orderbook if it gets accepted.
visible_quantity
behavior: it sets the maximum quantity to be shown on orderbook. By default, it is equal to order_quantity, negative number and number larger than order_quantity
is not allowed.
If it sets to 0, the order would be hidden from the orderbook.
It doesn't work for MARKET
/IOC
/FOK
orders since orders with these types would be executed and cancelled immediately and not be shown on orderbook.
For LIMIT
/POST_ONLY
order, as long as it's not complete, visible_quantity
is the maximum quantity that shown on orderbook.
order_amount
behavior: for MARKET
/BID
/ASK
order, order can be placed by order_amount
instead of order_quantity
. It's the size of the order in terms of the quote currency instead of the base currency. The order would be rejected if both order_amount
and order_quantity
are provided. The precision of the number should be within 8 digits.
client_order_id
behavior: customized order_id, a unique id among open orders. Orders with the same client_order_id
can be accepted only when the previous one if completed, otherwise the order will be rejected.
For MARKET
/BID
/ASK
order, if margin trading is disabled, order_amount
is not supported when placing SELL order while order_quantity
is not supported when placing BUY order.
Response
{
"success": true,
"order_id": 13,
"client_order_id": 0,
"order_type": "LIMIT",
"order_price": 100.12,
"order_quantity": 0.987654,
"order_amount": null,
"timestamp": "1639980423.855" // Unix epoch time in seconds
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y | |
client_order_id | number | N | number for scope : from 0 to 9223372036854775807. (default: 0) |
order_tag | string | N | An optional tag for this order. (default: default ) |
order_type | enum | Y | LIMIT /MARKET /IOC /FOK /POST_ONLY /ASK /BID |
order_price | number | N | If order_type is MARKET , then is not required, otherwise this parameter is required. |
order_quantity | number | N | For MARKET /ASK /BID order, if order_amount is given, it is not required. |
order_amount | number | N | For MARKET /ASK /BID order, the order size in terms of quote currency |
visible_quantity | number | N | The order quantity shown on orderbook. (default: equal to order_quantity ) |
side | enum | Y | SELL /BUY |
Cancel Order
Limit: 10 requests per 1 second shared with cancel_order_by_client_order_id
DELETE /v1/order
Cancel order by order id. The order cancelled information will be update from websocket stream. Note that we immediate response with an order cancel sent message, and will update the cancel event via websocket channel.
Response
{
"success": true,
"status": "CANCEL_SENT"
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
order_id | number | Y | The order_id that wish to cancel |
symbol | string | Y |
Cancel Order by client_order_id
Limit: 10 requests per 1 second shared with cancel_order
DELETE /v1/client/order
Cancel order by client order id. The order cancelled information will be update from websocket stream. Note that we immediate response with an order cancel sent message, and will update the cancel event via websocket channel.
Only the latest order with the symbol
and client_order_id
would be canceled.
Response
{
"success": true,
"status": "CANCEL_SENT"
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
client_order_id | number | Y | The client_order_id that wish to cancel |
symbol | string | Y |
Cancel Orders
Limit: 10 requests per 1 second
DELETE /v1/orders
Cancel orders by symbol.
Response
{
"success": true,
"status": "CANCEL_ALL_SENT"
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y |
Get Order
Limit: 10 requests per 1 second shared with get_order_by_client_order_id
GET /v1/order/:oid
Get specific order detail by order_id
.
Response
{
"success": true,
"created_time": "1577349119.33", // Unix epoch time in seconds
"side": "SELL",
"status": "FILLED",
"symbol": "SPOT_BTC_USDT",
"client_order_id": 0,
"order_id": 1,
"order_tag": "default",
"type": "LIMIT",
"price": 123,
"quantity": 0.1,
"amount": null,
"visible": 0.1,
"executed": 0.1,
"total_fee": 0.00123,
"fee_asset": "USDT",
"average_executed_price": 123,
// Detail transactions of this order
"Transactions": [
{
"id": 2,
"symbol": "SPOT_BTC_USDT",
"fee": 0.0001,
"fee_asset": "BTC", // fee. use Base (BTC) as unit when BUY, use Quote (USDT) as unit when SELL
"side": "BUY",
"order_id": 1,
"executed_price": 123,
"executed_quantity": 0.05,
"executed_timestamp": "1567382401.000", // Unix epoch time in seconds
"is_maker": 1
}]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
oid | number | Y | The order_id oid that wish to query |
Get Order by client_order_id
Limit: 10 requests per 1 seconds shared with get_order
GET /v1/client/order/:client_order_id
Get specific order detail by client_order_id
. If there are more than one orders with the same client_order_id
, return the latest one.
Response
{
"success": true,
"created_time": "1577349119.33", // Unix epoch time in seconds
"side": "SELL",
"status": "FILLED",
"symbol": "SPOT_BTC_USDT",
"client_order_id": 123,
"order_id": 1,
"order_tag": "default",
"type": "LIMIT",
"price": 123,
"quantity": 0.1,
"amount": null,
"visible": 0.1,
"executed": 0.1,
"total_fee": 0.00123,
"fee_asset": "USDT",
"average_executed_price": 123,
// Detail transactions of this order
"Transactions": [
{
"id": 2,
"symbol": "SPOT_BTC_USDT",
"fee": 0.0001,
"fee_asset": "BTC", // fee. use Base (BTC) as unit when BUY, use Quote (USDT) as unit when SELL
"side": "BUY",
"order_id": 1,
"executed_price": 123,
"executed_quantity": 0.05,
"executed_timestamp": "1567382401.000", // Unix epoch time in seconds
"is_maker": 1
}]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
client_order_id | number | Y | customized order_id when placing order |
Get Orders
Limit: 10 requests per 1 second
GET /v1/orders
Get orders by customize conditions.
- INCOMPLETE
= NEW
+ PARTIAL_FILLED
- COMPLETED
= CANCELLED
+ FILLED
Response
{
"success": true,
"meta": {
"total": 31,
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"side": "SELL",
"status": "CANCELLED",
"symbol": "SPOT_BCHABC_USDT",
"client_order_id": 123,
"order_id": 8197,
"order_tag": "default",
"type": "LIMIT",
"price": 308.51,
"quantity": 0.0019,
"amount": null,
"visible": 0.0019,
"executed": 0,
"total_fee": 0,
"fee_asset": null,
"created_time": "1575014255.089", // Unix epoch time in seconds
"updated_time": "1575014255.910", // Unix epoch time in seconds
"average_executed_price": null,
},
// ....skip (total 25 items in one page)
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | N | |
side | string | N | BUY /SELL |
order_type | string | N | LIMIT /MARKET /IOC /FOK /POST_ONLY /LIQUIDATE |
order_tag | string | N | An optional tag for this order. |
status | enum | N | NEW /CANCELLED /PARTIAL_FILLED /FILLED /REJECTED /INCOMPLETE /COMPLETED |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Orderbook snapshot
Limit: 10 requests per 1 second
GET /v1/orderbook/:symbol
SNAPSHOT of current orderbook. Price of asks/bids are in descending order.
Response
{
"success": true,
"asks": [
{
"price": 10669.4,
"quantity": 1.56263218
},
{
"price": 10670.3,
"quantity": 0.36466977
},
{
"price": 10670.4,
"quantity": 0.06738009
}
],
"bids": [
{
"price": 10669.3,
"quantity": 0.88159988
},
{
"price": 10669.2,
"quantity": 0.5
},
{
"price": 10668.9,
"quantity": 0.00488286
}
],
"timestamp": 1564710591905 // Unix epoch time in milliseconds
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
max_level | number | N (default: 100) | the levels wish to show on both side. |
Kline
Limit: 10 requests per 1 second
GET /v1/kline
The latest klines of the trading pairs.
Response
{
"success": true,
"rows": [
{
"open": 66166.23,
"close": 66124.56,
"low": 66038.06,
"high": 66176.97,
"volume": 23.45528526,
"amount": 1550436.21725288,
"symbol": "SPOT_BTC_USDT",
"type": "1m",
"start_timestamp": 1636388220000, // Unix epoch time in milliseconds
"end_timestamp": 1636388280000
},
{
"open": 66145.13,
"close": 66166.24,
"low": 66124.62,
"high": 66178.60,
"volume": 15.50705000,
"amount": 1025863.18892610,
"symbol": "SPOT_BTC_USDT",
"type": "1m",
"start_timestamp": 1636388160000,
"end_timestamp": 1636388220000
},
// ...skip
]
}
Kline - Historical Data
Limit: 10 requests per 1 second
GET https://api-pub.woo.org/v1/hist/kline
The historical klines of the trading pairs, the type only support 5m. Note that the endpoint is different with other API.
Response
{
"success": true,
"rows": [
{
"open": 66166.23,
"close": 66124.56,
"low": 66038.06,
"high": 66176.97,
"volume": 23.45528526,
"amount": 1550436.21725288,
"symbol": "SPOT_BTC_USDT",
"type": "1m",
"start_timestamp": 1636388220000, // Unix epoch time in milliseconds
"end_timestamp": 1636388280000
},
{
"open": 66145.13,
"close": 66166.24,
"low": 66124.62,
"high": 66178.60,
"volume": 15.50705000,
"amount": 1025863.18892610,
"symbol": "SPOT_BTC_USDT",
"type": "1m",
"start_timestamp": 1636388160000,
"end_timestamp": 1636388220000
},
// ...skip
]
"meta":{
"total":67377,
"records_per_page":100,
"current_page":1
}
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | Y | |
type | enum | Y | 5m /15m /30m /1h /4h /12h /1d /1w /1mon /1y |
start_time | number | Y | start range that wish to query, noted the time stamp is 13-digits timestamp. |
Get Trade
Limit: 10 requests per 1 second
GET /v1/client/trade/:tid
Get specific transaction detail by id
.
Response
{
"success": true,
"id": 1,
"symbol": "SPOT_BTC_USDT",
"fee": 0.0001,
"fee_asset": "BTC", // fee. use Base (BTC) as unit when BUY, use Quote (USDT) as unit when SELL
"side": "BUY",
"order_id": 2,
"executed_price": 123,
"executed_quantity": 0.05,
"is_maker": 0,
"executed_timestamp": "1567382400.000" // Unix epoch time in seconds
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
tid | number | Y | The transaction id tid that wish to query |
Get Trades
Limit: 10 requests per 1 second
GET /v1/order/:oid/trades
Get trades by order_id
Response
{
"success": true,
"rows": [
{
"id": 5, // transaction id
"symbol": "SPOT_BTC_USDT",
"order_id": 211,
"order_tag": "default",
"executed_price": 10892.84,
"executed_quantity": 0.002,
"is_maker": 0,
"side": "SELL",
"fee": 0,
"fee_asset": "USDT", // use Base (BTC) as unit when BUY, use Quote (USDT) as unit when SELL
"executed_timestamp": "1566264290.250" // Unix epoch time in seconds
},
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
oid | number | Y | The order id oid that wish to query |
Get History Trades
Limit: 10 requests per 1 second
GET /v1/client/trades
Return client’s trades history in a range of time.
Response
{
"success": true,
"meta": {
"total": 31,
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"id": 5, // transaction id
"symbol": "SPOT_BTC_USDT",
"order_id": 211,
"order_tag": "default",
"executed_price": 10892.84,
"executed_quantity": 0.002,
"is_maker": 0,
"side": "SELL",
"fee": 0,
"fee_asset": "USDT", // use Base (BTC) as unit when BUY, use Quote (USDT) as unit when SELL
"executed_timestamp": "1566264290.250" // Unix epoch time in seconds
},
// ....skip (total 25 items in one page)
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | N | |
order_tag | string | N | An optional tag for this order. |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Get Current Holding
Limit: 10 requests per 1 seconds
GET /v1/client/holding
Holding summary of client. Note that the number in holding could be negative, it means how much client owed to Wootrade.
Response
{
"success": true,
"holding": {
"BTC": 1.014,
"USDT": -26333.207589999998,
"BCHABC": 2
}
}
Parameters
None
Get Current Holding v2
Limit: 10 requests per 1 seconds
GET /v2/client/holding
Holding summary of client. Note that the number in holding could be negative, it means how much client owed to Wootrade.
Response
{
"success": true,
"holding": [
{
"updated_time": "1580794149", // Unix epoch time in seconds
"token": "BTC",
"holding": -28.000752,
"frozen": 0,
"outstanding_holding": -1,
"pending_exposure": 12000,
"interest": -0.01
},
{
"updated_time": "1580794149",
"token": "USDT",
"holding": 282485.071904,
"frozen": 0,
"outstanding_holding": -2000,
"pending_exposure": 0,
"interest": -10
}
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
all | enum | N | true /false . If true then will return all token even if balance is empty. |
Get Account Information
Limit: 10 requests per 60 seconds
GET /v1/client/info
Get account information such as account name, leverage, current exposure ... etc.
Response
{
"success": true,
"application": {
"application_id": "8935820a-6600-4c2c-9bc3-f017d89aa173",
"account": "CLIENT_ACCOUNT_01",
"alias": "CLIENT_ACCOUNT_01",
"account_mode":"FUTURES" //account mode
"leverage": 5,
"taker_fee_rate": 0,
"maker_fee_rate": 0,
"interest_rate": 0,
"futures_leverage": 5,
"futures_taker_fee_rate": 0,
"futures_maker_fee_rate": 0,
"otpauth": false
},
"margin_rate": 1000
}
Parameters
None
Get Token Deposit Address
Limit 5 requests per 60 seconds
GET /v1/asset/deposit
Get your unique deposit address by token
Response
{
"success": true,
"address": "0x31d64B3230f8baDD91dE1710A65DF536aF8f7cDa",
"extra": ""
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | Y | token name you want to deposit (can get it by /public/token) |
Get Asset History
Limit 10 requests per 60 seconds
GET /v1/asset/history
Get asset history, includes token deposit/withdraw and collateral deposit/withdraw.
Response
{
"success": true,
"meta": {
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"created_time": "1579399877.041", // Unix epoch time in seconds
"updated_time": "1579399877.041", // Unix epoch time in seconds
"id": "202029292829292",
"external_id": "202029292829292",
"application_id": null,
"token": "ETH",
"target_address": "0x31d64B3230f8baDD91dE1710A65DF536aF8f7cDa",
"source_address": "0x70fd25717f769c7f9a46b319f0f9103c0d887af0",
"extra": "",
"type": "BALANCE",
"token_side": "DEPOSIT",
"amount": 1000,
"tx_id": "0x8a74c517bc104c8ebad0c3c3f64b1f302ed5f8bca598ae4459c63419038106b6",
"fee_token": null,
"fee_amount": null,
"status": "CONFIRMING"
},
{
"created_time": "1579399877.041",
"updated_time": "1579399877.041",
"id": "20202020202020022",
"external_id": "20202020202020022",
"application_id": null,
"token": "ETH",
"target_address": "0x31d64B3230f8baDD91dE1710A65DF536aF8f7cDa",
"source_address": "0x70fd25717f769c7f9a46b319f0f9103c0d887af0",
"extra": "",
"type": "BALANCE",
"token_side": "DEPOSIT",
"amount": 100,
"tx_id": "0x7f74c517bc104c8ebad0c3c3f64b1f302ed5f8bca598ae4459c63419038106c5",
"fee_token": null,
"fee_amount": null,
"status": "COMPLETED"
}
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | N | token name you want to search (can get it by /public/token) |
balance_token | string | N | balance_token name you want to search (can get it by /public/token) |
type | string | N | BALANCE /COLLATERAL |
token_side | string | N | DEPOSIT /WITHDRAW |
status | string | N | NEW /CONFIRMING /PROCESSING /COMPLETED /CANCELED |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Margin Interest Rates
Limit 10 requests per 60 seconds
GET /v1/token_interest
Get the margin interest rate of each token.
Response
{
"success": true,
"rows": [
{
"token": "MATIC",
"current_hourly_base_rate": "0.0001%",
"est_hourly_base_rate": "0.0001%",
"current_annual_base_rate": "0.876%",
"est_annual_base_rate": "0.876%",
"est_time": "1632394800.000" // Unix epoch time in seconds
},
{
"token": "USDT",
"current_hourly_base_rate": "0.0008%",
"est_hourly_base_rate": "0.0008%",
"current_annual_base_rate": "7.008%",
"est_annual_base_rate": "7.008%",
"est_time": "1632394800.000" // Unix epoch time in seconds
},
{
"token": "WOO",
"current_hourly_base_rate": "0.001%",
"est_hourly_base_rate": "0.001%",
"current_annual_base_rate": "8.76%",
"est_annual_base_rate": "8.76%",
"est_time": "1632394800.000" // Unix epoch time in seconds
},
// ...
]
}
Parameters
None
Margin Interest Rate of Token
Limit 10 requests per 60 seconds
GET /v1/token_interest/:token
Get the margin interest rate of the specific token.
Response
{
"success": true,
"info": {
"token": "BTC",
"current_hourly_base_rate": "0.0001%",
"est_hourly_base_rate": "0.0001%",
"current_annual_base_rate": "0.876%",
"est_annual_base_rate": "0.876%",
"est_time": "1632448800.000" // Unix epoch time in seconds
}
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | Y | should be upper case |
Get Interest History
Limit 10 requests per 60 seconds
GET /v1/interest/history
Get margin interest history.
Response
{
"success": true,
"meta": {
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"created_time": "1579399877.041", // Unix epoch time in seconds
"updated_time": "1579399877.041", // Unix epoch time in seconds
"token": "USDT",
"application_id": null,
"side": "LOAN",
"interest": "1",
}
]
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | N | interest token which you want to query |
side | string | N | LOAN /REPAY /AUTO_REPAY |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Repay Interest
Limit 10 requests per 60 seconds
POST /v1/interest/repay
REPAY your margin interest.
Response
{
"success": true,
}
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | Y | interest token which you want to repay |
amount | number | Y | repayment amount |
Get Subaccounts
Limit: 10 requests per 60 seconds
GET /v1/sub_account/all
Get subaccount list.
Response
{
"rows": [
{
"application_id": "6b43de5c-0955-4887-9862-d84e4689f9fe",
"account": "2",
"created_time": "1606897264.994"
},
{
"application_id": "5b0df321-3aaf-471f-a386-b922a941d17d",
"account": "1",
"created_time": "1606897264.994"
},
{
"application_id": "de25e672-f3e8-4ddc-b264-75d243cb2b9c",
"account": "test",
"created_time": "1606897264.994"
}
],
"success": true
}
Permission
Main account only.
Parameters
None
Get Assets of Subaccounts
Limit: 10 requests per 60 seconds
GET /v1/sub_account/assets
Get assets summary of all subaccounts (including main account).
Response
{
"rows": [
{
"application_id": "0b297f58-9d3e-4c91-95cd-863329631b79",
"account": "Main",
"usdt_balance": 0.0
}
],
"success": true
}
Permission
Main account only.
Parameters
None
Get Asset Detail of a Subaccount
Limit: 10 requests per 60 seconds
GET /v1/sub_account/asset_detail
Get assets detail of a subaccounts.
Response
{
"balances": {
"BTC": {
"holding": 0.0,
"frozen": 0.0,
"interest": 0.0,
"staked": 0.0,
"unbonding": 0.0,
"vault": 0.0
},
"WOO": {
"holding": 4172706.29647137,
"frozen": 0.0,
"interest": 0.0,
"staked": 51370692,
"unbonding": 0.0,
"vault": 0.0
},
"BNB": {
"holding": 0.00070154,
"frozen": 0.0,
"interest": 0.0,
"staked": 0.0,
"unbonding": 0.0,
"vault": 0.0
},
"ETH": {
"holding": 0.0,
"frozen": 0.0,
"interest": 0.0,
"staked": 0.0,
"unbonding": 0.0,
"vault": 0.0
},
"USDT": {
"holding": 14066.5839369,
"frozen": 0.0,
"interest": 0.0,
"staked": 0.0,
"unbonding": 0.0,
"vault": 0.0
}
},
"account": "test",
"success": true,
"application_id": "e074dd6b-4c03-49be-937f-856472f7a6cb"
}
Permission
Main or Subaccounts.
Parameters
Name | Type | Required | Description |
---|---|---|---|
application_id | string | Y | application id for an account, user can find it from WOO X console. |
Get IP Restriction
Limit: 10 requests per 10 seconds
GET /v1/sub_account/ip_restriction
Get allowed IP list of a subaccount's API Key.
Response
{
"rows": [
{
"ip_list": "60.248.33.61,1.2.3.4,100.100.1.1,100.100.1.2,100.100.1.3,100.100.1.4,210.64.18.77",
"api_key": "plXHR+GwX0u8UG/GwMjLsQ==",
"update_time": "1644553230.916",
"restrict": true
}
],
"meta": {
"total": 1,
"records_per_page": 25,
"current_page": 1
},
"success": true
}
Permission
Main or Subaccounts.
Parameters
Name | Type | Required | Description |
---|---|---|---|
application_id | string | N | from WOO X console |
api_key | string | N | created from WOO X console |
Get Transfer History
Limit: 20 requests per 60 seconds
GET /v1/asset/main_sub_transfer_history
Get transfer history between main account and subaccounts.
Response
{
"success":true,
"data":{
"rows":[
{
"id":225,
"token":"USDT",
"amount":1000000,
"status":"COMPLETED",
"from_application_id":"046b5c5c-5b44-4d27-9593-ddc32c0a08ae",
"to_application_id":"082ae5ae-e26a-4fb1-be5b-03e5b4867663",
"from_user":"Main",
"to_user":"av",
"created_time":"1642660941.534",
"updated_time":"1642660941.950"
},
// ....skip (total 25 items in one page)
],
"meta":{
"total":7,
"records_per_page":5,
"current_page":1
}
}
}
Permission
Main or Subaccounts.
Parameters
Name | Type | Required | Description |
---|---|---|---|
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Transfer Assets
Limit: 20 requests per 60 seconds
POST /v1/asset/main_sub_transfer
Transfer asset between main account and subaccounts.
Response
{
"success": true,
"id": 200
}
Permission
Main or Subaccounts.
Parameters
Name | Type | Required | Description |
---|---|---|---|
token | string | Y | token name you want to transfer (can get it by /public/token) |
amount | number | Y | amount you want to transfer |
from_application_id | string | Y | application id you want to transfer from |
to_application_id | string | Y | application id you want to transfer to |
Update Account Mode
Limit: 5 requests per 60 second per user
POST /v1/client/account_mode
Choose account mode: pure spot or margin or futures
Parameters
Name | Type | Required | Description |
---|---|---|---|
account_mode | string | Y | PURE_SPOT, MARGIN, FUTURES |
Response
{
"success": true
}
Update Leverage Setting
Limit: 5 requests per 60 second per user
POST /v1/client/leverage
Choose maximum leverage for margin mode or futures mode
Parameters
Name | Type | Required | Description |
---|---|---|---|
leverage | int | Y | for margin mode: 3, 4, 5 ; for futures mode: 1, 2, 3, 4, 5, 10, 15, 20 |
Response
{
"success": true
}
Get Funding Fee History
Limit: 20 requests per 60 second per user
GET /v1/funding_fee/history
Get funding fee history
Parameters
Name | Type | Required | Description |
---|---|---|---|
symbol | string | N | symbol that wish to query |
start_t | timestamp | N | start time range that wish to query, noted the time stamp is 13-digits timestamp. |
end_t | timestamp | N | end time range that wish to query, noted the time stamp is 13-digits timestamp. |
page | number | N (default: 1) | the page wish to query. |
Response
{
"success": true,
"meta": {
"total": 670,
"records_per_page": 25,
"current_page": 1
},
"rows": [
{
"id": 10001,
"symbol": "PERP_BTC_USDT",
"funding_rate": 0.00345,
"mark_price": 100,
"funding_fee": 0.345,
"payment_type": "Receive", // Receive and Pay
"status": "COMPLETED",
"created_time": "1575014255.089", // Unix epoch time in seconds
"updated_time": "1575014255.910" // Unix epoch time in seconds
},
// ....skip (total 25 items in one page)
}
Get All Position info
Limit: 10 requests per 10 second per user
GET /v1/positions
Parameters
Response
{
"success": true,
"current_margin_ratio": 0.8,
"initial_margin_ratio": 0.8,
"maintenance_margin_ratio": 0.8,
"total_collateral": 100,
"free_collateral": 80,
"total_account_value": 150,
"total_vault_value": 10,
"total_staking_value": 5,
"positions": [
{
"symbol": "PERP_BTC_USDT",
"holding": 1.23,
"pending_long_qty": 0.5,
"pending_short_qty": 0.23,
"settle_price": 50000,
"average_open_price": 49000,
"pnl_24_h": 20,
"fee_24_h": 12,
"mark_price": 49550,
"est_liq_price": 40000,
"timestamp": "1575014255.089"
},
// ....skip
]
}
Get One Position info
Limit: 10 requests per 10 second per user
GET /v1/positions/:symbol
Parameters
Response
{
"success": true,
"symbol": "PERP_BTC_USDT",
"holding": 1.23,
"pending_long_qty": 0.5,
"pending_short_qty": 0.23,
"settle_price": 50000,
"average_open_price": 49000,
"pnl_24_h": 20,
"fee_24_h": 0.2,
"mark_price": 49550,
"est_liq_price": 40000,
"timestamp": "1575014255.089"
}
Websocket API V2
Market Data Base endpoints:
wss://wss.woo.org/ws/stream/{application_id}
{application_id}
user can find application_id from console- user can subscribe/unsubscribe
orderbook
|orderbook100
|aggbook10
|aggbook100
|aggbook1000
|ticker
|tickers
|bbo
|trade
|kline_1m
|kline_5m
|kline_15m
|kline_30m
|kline_1h
|kline_1d
|kline_1w
|kline_1M
Private User Data Stream Base endpoints:
wss://wss.woo.network/v2/ws/private/stream/{application_id}
{application_id}
user can find application_id from console- user need to be authenticated before subscribing any topic, would be disconnected if fail the authentication. See refer to Authenticaton for more information.
- user can subscribe/unsubscribe
positioninfo
|executionreport
PING/PONG
- The server will send a ping command to the client every 10 seconds. If the pong from client is not received within 10 seconds for 10 consecutive times, it will actively disconnect the client.
- The client can also send ping every 10s to keep alive.
Parameters
Name | Type | Required | Description |
---|---|---|---|
event | string | Y | ping /pong |
{
"event":"ping"
}
Response
{
"event":"pong",
"ts":1614667590000
}
request orderbook
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | request |
params.type | string | Y | orderbook |
params.symbol | string | Y | {symbol} |
{
"id": "clientID1",
"event": "request",
"params": {
"type": "orderbook",
"symbol": "SPOT_BTC_USDT"
}
}
Response
{
"id":"123r",
"event":"request",
"success":true,
"ts":1618880432419,
"data":{
"symbol":"SPOT_BTC_USDT",
"ts":1618880432380,
"asks":[
[
54700,
0.443951
],
[
54700.02,
0.002566
],
...
],
"bids":[
[
54699.99,
2.887466
],
[
54699.76,
2.034711
],
...
]
}
}
orderbook
{symbol}@orderbook
depth 100 push every 1s{symbol}@orderbook100
depth 100 push every 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@orderbook /{symbol}@orderbook100 |
{
"id": "clientID2",
"topic": "SPOT_WOO_USDT[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID2",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic": "[email protected]",
"ts": 1614152140945,
"data": {
"symbol": "SPOT_WOO_USDT",
"asks": [
[
0.31075,
2379.63
],
[
0.31076,
4818.76
],
[
0.31078,
8496.1
],
...
],
"bids": [
[
0.30891,
2469.98
],
[
0.3089,
482.5
],
[
0.30877,
20
],
...
]
}
}
orderbookupdate
{symbol}@orderbookupdate
updated orderbook push every 200ms
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@orderbookupdate |
{
"id": "clientID2",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID2",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618826337580,
"data":{
"symbol":"SPOT_BTC_USDT",
"prevTs":1618826337380,
"asks":[
[
56749.15,
3.92864
],
[
56749.8,
0
],
...
],
"bids":[
[
56745.2,
1.03895025
],
[
56744.6,
1.0807
],
...
]
}
}
trade
- Push interval: real-time push
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@trade |
{
"id": "clientID3",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618820361552,
"data":{
"symbol":"SPOT_ADA_USDT",
"price":1.27988,
"size":300,
"side":"BUY"
}
}
24h ticker
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@ticker |
{
"id": "clientID4",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID4",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic": "[email protected]",
"ts": 1614152270000,
"data": {
"symbol": "SPOT_WOO_USDT",
"open": 0.16112,
"close": 0.32206,
"high": 0.33000,
"low": 0.14251,
"volume": 89040821.98,
"amount": 22493062.21,
"count": 15442
}
}
24h tickers
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | tickers |
{
"id": "clientID4",
"topic": "tickers",
"event": "subscribe"
}
Response
{
"id": "clientID4",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"tickers",
"ts":1618820615000,
"data":[
{
"symbol":"SPOT_OKB_USDT",
"open":16.297,
"close":17.183,
"high":24.707,
"low":11.997,
"volume":0,
"amount":0,
"count":0
},
{
"symbol":"SPOT_XRP_USDT",
"open":1.3515,
"close":1.43794,
"high":1.96674,
"low":0.39264,
"volume":750127.1,
"amount":985440.5122,
"count":396
},
...
]
}
bbo
- Push interval: 10ms
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@bbo |
{
"id": "clientID5",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID5",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic": "[email protected]",
"ts": 1614152296945,
"data": {
"symbol": "SPOT_WOO_USDT",
"ask": 0.30939,
"askSize": 4508.53,
"bid": 0.30776,
"bidSize": 25246.14
}
}
bbos
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | bbos |
{
"id": "clientID5",
"topic": "bbos",
"event": "subscribe"
}
Response
{
"id": "clientID5",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"bbos",
"ts":1618822376000,
"data":[
{
"symbol":"SPOT_FIL_USDT",
"ask":159.0318,
"askSize":370.43,
"bid":158.9158,
"bidSize":16
},
{
"symbol":"SPOT_BTC_USDT",
"ask":56987.18,
"askSize":3.163881,
"bid":56987.17,
"bidSize":0.941728
},
...
]
}
k-line
{time}
:1m
/5m
/15m
/30m
/1h
/1d
/1w
/1M
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | N | {symbol}@kline_{time} |
{
"id": "clientID6",
"topic": "[email protected]_1m",
"event": "subscribe"
}
Response
{
"id": "clientID6",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]_1m",
"ts":1618822432146,
"data":{
"symbol":"SPOT_BTC_USDT",
"type":"1m",
"open":56948.97,
"close":56891.76,
"high":56948.97,
"low":56889.06,
"volume":44.00947568,
"amount":2504584.9,
"startTime":1618822380000,
"endTime":1618822440000
}
}
auth
- refer to Authenticaton for more details about how to sign the request with
api_key
andapi_secret
. query string and body parameters are both blank.
Parameters
Name | Type | Required | Description |
---|---|---|---|
apikey | string | Y | api key |
sign | string | Y | sign |
timestamp | string | Y | timestamp |
{
"id":"123r",
"event":"auth",
"params":{
"apikey":"CUS69ZJOXwSV38xo...",
"sign":"4180da84117fc9753b...",
"timestamp":"1621910107900"
}
}
Response
{
"id":"123r",
"event":"auth",
"success":true,
"ts":1621910107315
}
positioninfo
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | positioninfo |
{
"id": "clientID3",
"topic": "positioninfo",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"positioninfo",
"ts":1618757307607,
"data":{
"marginRate":95.87,
"marginMode":"MARGIN",
"leverage":3,
"takerFeeRate":5,
"makerFeeRate":0,
"interestRate":3,
"guiTakerFeeRate":5,
"guiMakerFeeRate":0,
"liquidationMarginRate":95.87,
"futuresLeverage":1,
"futuresApiTakerFeeRate":5,
"futuresApiMakerFeeRate":0,
"futuresGuiTakerFeeRate":5,
"futuresGuiMakerFeeRate":0,
"positions":{
"BSV":{
"holding":0,
"outstandingHolding":0,
"pendingExposure":0,
"interest":0,
"avgOpenPrice":0,
"breakEvenPrice":0,
"realisedPnl":0,
"settledPnl":0,
"markPx":309.8,
"liquidPx":0,
"pnl24H":0,
"fee24H":0,
"frozen":0
},
"BCH":{
"holding":0,
"outstandingHolding":0,
"pendingExposure":0,
"interest":0,
"avgOpenPrice":0,
"breakEvenPrice":0,
"realisedPnl":0,
"settledPnl":0,
"markPx":909.19,
"liquidPx":0,
"pnl24H":0,
"fee24H":0,
"frozen":0
},
...
}
}
}
executionreport
- Push interval: real-time push
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | executionreport |
{
"id": "clientID3",
"topic": "executionreport",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"executionreport",
"ts":1618757714353,
"data":{
"symbol":"SPOT_XRP_USDT",
"clientOrderId":0,
"orderId":4506424,
"type":"LIMIT",
"side":"BUY",
"quantity":750127.1,
"price":11,
"tradeId":1870568,
"executedPrice":1.32014,
"executedQuantity":6620.6,
"fee":1.98618,
"feeAsset":"XRP",
"totalExecutedQuantity":720891.2,
"avgPrice":1.31344,
"status":"PARTIAL_FILLED",
"reason":"",
"orderTag":"default",
"totalFee":216.26736,
"timestamp":1618757714353,
"maker":false
}
}
indexprice
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@indexprice |
{
"id": "clientID3",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618820361552,
"data":{
"symbol":"SPOT_ETH_USDT",
"price":3987.1
}
}
markprice
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@markprice |
{
"id": "clientID3",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618820361552,
"data":{
"symbol":"PERP_ETH_USDT",
"price":3987.2
}
}
openinterest
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@openinterest |
{
"id": "clientID3",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618820361552,
"data":{
"symbol":"PERP_BTC_USDT",
"openInterest":1.27988
}
}
estfundingrate
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | {symbol}@estfundingrate |
{
"id": "clientID3",
"topic": "[email protected]",
"event": "subscribe"
}
Response
{
"id": "clientID3",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"[email protected]",
"ts":1618820361552,
"data":{
"symbol":"PERP_BTC_USDT",
"fundingRate":1.27988,
"fundingTs":1618820361552
}
}
markprices
- Push interval: 1s
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe /unsubscribe |
topic | string | Y | markprices |
{
"id": "clientID5",
"topic": "markprices",
"event": "subscribe"
}
Response
{
"id": "clientID5",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"markprices",
"ts":1618822376000,
"data":[
{
"symbol":"PERP_BTC_USDT",
"price":51234.13
},
{
"symbol":"PERP_ETH_USDT",
"price":3894.34
},
...
]
}
position push
- Push interval: push on update
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | Y | id generate by client |
event | string | Y | subscribe/ unsubscribe |
topic | string | Y | position |
{
"id": "clientID5",
"topic": "position",
"event": "subscribe"
}
Response
{
"id": "clientID5",
"event": "subscribe",
"success": true,
"ts": 1609924478533
}
Subscribed Message
{
"topic":"position",
"ts":1641439456774,
"data":[
{
"symbol":"PERP_BTC_USDT",
"holding":1.23,
"pendingLongQty":1.2,
"pendingShortQty":0.3,
"pnl24H":20,
"fee24H":12,
"avgOpenPrice":49000,
"settlePrice":50000,
"markPrice": 49500,
}
]
}
error response
{
"id": "clientID7",
"event": "subscribe",
"success": false,
"ts": 1614141150601,
"errorMsg": "invalid symbol SPOT_WOO_USDC"
}
Release Note
All the API changes would be listed here.
2022-06-10
- Add
total_collateral
,free_collateral
,total_account_value
,total_vault_value
,total_staking_value
andest_liq_price
for each futures positions in Position Info. - Deprecate websocket subscription topic: Orderbook depth 1000, the original {symbol}@orderbook topic will keep alive but push the same data as [email protected] (depth 100).
2022-05-23
- Upgrade websocket subscription topic: bbo push frequency from 200ms to 10ms.
- Add public API for Historical Kline.
2022-03-21
- Add public API for Funding Rate and Futures Info.
- Add private API for Change Account mode, Change Leverage.
- Add private API for Funding Fee, Position Info.
- Add
account_mode
,futures_leverage
,futures_taker_fee_rate
,futures_maker_fee_rate
in Account Information. - Add
futures_margin_factor
in Token Config, - Add Websocket Topics indexprice, markprice, openinterest, estfundingrate, markprices, position push
2022-02-25
- Add API SubAccount to manage subaccounts.
2022-01-17
- Add
can_collateral
,can_short
andstable
in Token_Config
2021-12-24
Add API Kline to query yearly Kline.
Add
client_order_id
andtimestamp
in the response message of API Send_Order.
2021-11-12
- Add API Kline to provide at most 1000 klines.
2021-10-22
Add Public API Token Network to query the token deposit/withdrawal information on each network.
Add rate limit on public APIs.
2021-09-27
- Add API Margin_Interest_Rates and Margin_Interest_Rate_of_Token to query the margin interest rates.
2021-09-06
Adjust rate limit of API Get_Order and Get_Order_by_client_order_id to 10 per second in total.
Adjust rate limit of API Cancel_Order and Cancel_Order_by_client_order_id to 10 per second in total.
Adjust rate limit of API Get_Trade, Get_Trades to 10 per second for each.
2021-09-03
- Add API Token_Config
2021-08-06
Remove
Transactions
from Get_OrdersAdd
total_fee
andfee_asset
in Get_Order, Get_Order_by_client_order_id, Get_Orders
2021-07-09
- Websocket topic positioninfo stop pushing the tokens that have never been traded before to reduce the message size.
2021-06-25
- Add API Cancel_Order_by_client_order_id
User could cancel order by the user-specified client_order_id
.
- Add API Get_Trades
User could get all the trades by order_id
.
- Adjust rate limit of API Send_Order from 120 per minute to 2 per second per symbol