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:

{
  "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:

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.

order_price=9000&order_quantity=0.11&order_type=LIMIT&side=BUY&symbol=SPOT_BTC_USDT|1578565539808

$ 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 zero
price <= asks[0].price * (1 + price_range) when BUY
price >= 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 than min_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

{
    "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

{
  "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.

{
    "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.

{
    "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.

{
    "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

Token Config

Limit: 10 requests per 1 second

GET /v1/client/token

Get the configuration (collateral ratio, margin ratio factor etc) of the token.

{
    "success": true,
    "rows": [
        {
            "token": "BTC",
            "collateral_ratio": 0.85,
            "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,
            "collateral": true,
            "can_collateral": true,
            "can_short": true,
            "stable": false
        },
        {
            "token": "ASD",
            "collateral_ratio": 1,
            "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
    "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.

{
    "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

{
    "success": true,
    "meta": {
        "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.

{
    "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.

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

Parameters

Name	Type	Required	Description
symbol	string	Y
type	enum	Y	`1m`/`5m`/`15m`/`30m`/`1h`/`4h`/`12h`/`1d`/`1w`/`1mon`/`1y`
limit	number	N (default: 100)	Numbers of klines. Maximum of 1000 klines.

Get Trade

Limit: 10 requests per 1 second

GET /v1/client/trade/:tid

Get specific transaction detail by id.

{
    "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

{
    "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.

{
    "success": true,
    "meta": {
        "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.

{
    "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.

{
  "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.

{
    "success": true,
    "application": {
        "application_id": "8935820a-6600-4c2c-9bc3-f017d89aa173",
        "account": "CLIENT_ACCOUNT_01",
        "leverage": 5,
        "taker_fee_rate": 0,
        "maker_fee_rate": 0,
        "interest_rate": 0,
        "alias": "CLIENT_ACCOUNT_01",
        "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

{
    "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.

{
    "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.

Get Asset Transfer History

Limit 10 requests per 60 seconds

GET /v1/asset/transfer_history

Get asset transfer history.

{
    "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": "202029292829293",
            "application_id": null,
            "from": "COLLATERAL",
            "to": "BALANCE",
            "amount": 1000,
        },
        {
           "created_time": "1579399877.041",
           "updated_time": "1579399877.041",
           "id": "202029292829292",
           "application_id": null,
           "from": "BALANCE",
           "to": "COLLATERAL",
           "amount": 500,
        }
    ]
}

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.

Margin Interest Rates

Limit 10 requests per 60 seconds

GET /v1/token_interest

Get the margin interest rate of each token.

{
    "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.

{
    "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.

{
    "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.

{
    "success": true,
}

Parameters

Name	Type	Required	Description
token	string	Y	interest token which you want to repay
amount	number	Y	repayment amount

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 1000 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": "[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: 1s

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 and api_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":1000,
        "leverage":2,
        "takerFeeRate":5,
        "makerFeeRate":0,
        "interestRate":0,
        "withdrawDayBtcValue":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
    }
}

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-01-17

Add can_collateral, can_short and stable in Token_Config

2021-12-24

Add API Kline to query yearly Kline.
Add client_order_id and timestamp 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_Orders
Add total_fee and fee_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