Order

API Scopes

GET request need Permission to view order information, POST request need Permission to create orders.

Order

Attribute Name	Type	Description	Example
id	number	id of order
asset_pair_name	string	name of asset pair
price	string	order price
amount	string	order amount
filled_amount	string	already filled amount
avg_deal_price	string	average price of the deal
side	string	order side, one of ASK,BID
state	string	order status, one of FILLED,PENDING,CANCELLED,FIRED,REJECTED
created_at	string	created time
updated_at	string	updated time
type	string	order type, one of LIMIT,MARKET,STOP_LIMIT,STOP_MARKET
stop_price	string	order stop price, only for stop order
operator	string	operator, one of GTE,LTE
immediate_or_cancel	bool	only use in LIMIT type
post_only	bool	only use in LIMIT type
client_order_id	string	client order id, assigned by the customer himself to identify the order. must match ^[a-zA-Z0-9-_]{1,36}$ this regex.

Get user orders in one asset pair

GET /viewer/orders

Parameters

Name	Type	Require	Description	Example
asset_pair_name	string	true	asset pair Name	BTC-USDT
page_token	string	false	request page after this page token
side	string	false	order side, one of ASK,BID
state	string	false	order state, one of PENDING,OPENING,CLOSED,NONE_FILLED,ALL. default is PENDING. CLOSED as a query parameter indicates order state FILLED and CANCELLED. OPENING or PENDING as a query parameter indicates order state FIRED and PENDING; NONE_FILLED is used for querying the orders which state is closed and filled amount is zero. ALL return customer all orders
limit	string	false	default 20; max 200.

Response is Order array.

{
  "data": [{
      "id": 10,
      "asset_pair_name": "EOS-BTC",
      "price": "10.00",
      "amount": "10.00",
      "filled_amount": "9.0",
      "avg_deal_price": "12.0",
      "side": "ASK",
      "state": "FILLED",
      "type": "LIMIT",
      "stop_price": "9.8",
      "operator": "LTE",
      "immediate_or_cancel": true,
      "post_only": false,
      "client_order_id": "",
      "created_at":"2019-01-29T06:05:56Z",
      "updated_at":"2019-01-29T06:05:56Z"
    }],
    "page_token":"dxzef"
}

Get one order

1. Get order by id in path:

GET /viewer/orders/{id}

Parameters

Name	Type	Require	Description	Example
id	string	true	order id	10

2. Get order by id or client_order_id in query:

GET /viewer/order

Parameters

Name	Type	Require	Description	Example
order_id	string	false	order id	10
client_order_id	string	false	client order id

Either order_id or client_order_id must be sent. If both order_id and client_order_id are provided, order_id takes precedence.

Response is Order object.

{
  "id": 10,
  "asset_pair_name": "EOS-BTC",
  "price": "10.00",
  "amount": "10.00",
  "filled_amount": "9.0",
  "avg_deal_price": "12.0",
  "side": "ASK",
  "state": "FILLED",
  "type": "LIMIT",
  "stop_price": "9.8",
  "operator": "LTE",
  "immediate_or_cancel": true,
  "post_only": false,
  "client_order_id": "",
  "created_at":"2019-01-29T06:05:56Z",
  "updated_at":"2019-01-29T06:05:56Z"
}

Create Order

POST /viewer/orders

Parameters

Name	Type	Require	Description	Example
asset_pair_name	string	true	asset pair name	BTC-USDT
side	string	true	order side, one of ASK,BID
price	string	false	order price
amount	string	true	must larger than 0
type	string	true	order type, one of LIMIT,MARKET,STOP_LIMIT,STOP_MARKET, default LIMIT
stop_price	string	false	must larger than 0, only for stop order. in BID side, price cannot be higher than 110% of the stop_price; in ASK side, price cannot be lower than 90% of the stop_price
operator	string	false	operator, one of GTE,LTE, only for stop order, GTE(>=) – greater than or equal to, LTE(<=) – less than or equal to
immediate_or_cancel	bool	false	only use with LIMIT type, must be false when post_only is true
post_only	bool	false	only use with LIMIT type, must be false when immediate_or_cancel is true
client_order_id	string	false	must match ^[a-zA-Z0-9-_]{1,36}$ this regex. client_order_id is unique in 24 hours, If created 24 hours later and the order closed, it will be released and can be reused

Additional required parameters based on type:

Type	Additional required parameters
LIMIT	price
STOP_LIMIT	price,stop_price, operator
STOP_MARKET	stop_price, operator

Other info:

• LIMIT,STOP_LIMIT,MARKET ASK, STOP_MARKET ASK orders using the amount field specifies the amount of the base asset the user wants to buy or sell; scale of amount should less than or equal to AssetPair's base scale.
• MARKET BID, STOP_MARKET BID orders using amount specifies the amount the user wants to spend the quote asset; the correct quantity will be determined based on the market liquidity and amount; scale of amount should less than or equal to AssetPair's quote scale.
• price's scale should less than AssetPair's quote scale
• For LIMIT,STOP_LIMIT orders, price * amount should larger than AssetPair's min_quote_value
• Request body should be a json string. The header of Content-Type should be application/json

Http request example (raw data):

POST /api/v3/viewer/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTAwMiwiaWRlbnRpdHkiOm51bGwsInR5cGUiOiJCYXNpYyIsImV4cCI6MTU1MDc0MDM1NCwiaWF0IjoxNTUwNDgxMTU0LCJpc3MiOiJCcm9rZXIiLCJuYmYiOjE1NTA0ODExNTMsInN1YiI6MTAwMn0.4cZZ7hFOyfbROr8EZ6-lu20W--T-P35iSOLMOQuqWp8
Host: b1.run
Connection: close

{"asset_pair_name":"BTC-USDT","side":"ASK","price":"10001","amount":"0.1", "type":"STOP_LIMIT", "stop_price":"10000", "operator":"GTE"}

Response is Order object:

{
  "id": 10,
  "asset_pair_name": "EOS-BTC",
  "price": "10.00",
  "amount": "10.00",
  "filled_amount": "9.0",
  "avg_deal_price": "12.0",
  "side": "ASK",
  "state": "FILLED",
  "type": "STOP_LIMIT",
  "stop_price": "9.8",
  "operator": "LTE",
  "immediate_or_cancel": false,
  "post_only": true,
  "client_order_id": "",
  "created_at":"2019-01-29T06:05:56Z",
  "updated_at":"2019-01-29T06:05:56Z"
}

Multiple Create Orders

POST /viewer/orders/multi

Only Limit or Market order is allowed to multiple create, Stop order is not allowed. The quantity limit of multiple create orders: 10

Notice: If an error occurs in it, all order creations fail.

Parameters

Name	Type	Require	Description	Example
asset_pair_name	string	true	asset pair name	BTC-USDT
side	string	true	order side, one of ASK, BID
price	string	false	order price
amount	string	true	must larger than 0
type	string	true	order type, one of LIMIT,MARKET
immediate_or_cancel	bool	false	only use with LIMIT type, must be false when post_only is true
post_only	bool	false	only use with LIMIT type, must be false when immediate_or_cancel is true
client_order_id	string	false	must match ^[a-zA-Z0-9-_]{1,36}$ this regex. client_order_id is unique in 24 hours, If created 24 hours later and the order closed, it will be released and can be reused

Request body example:

[{
  "asset_pair_name": "EOS-BTC",
  "price": "10.00",
  "side": "ASK",
  "amount": "1",
  "type": "STOP_LIMIT",
  "stop_price": "9.8",
  "operator": "LTE",
  "immediate_or_cancel": false,
  "post_only": true,
}]

Response is Order array:

[{
  "id": 10,
  "asset_pair_name": "EOS-BTC",
  "price": "10.00",
  "amount": "10.00",
  "filled_amount": "9.0",
  "avg_deal_price": "12.0",
  "side": "ASK",
  "state": "FILLED",
  "type": "STOP_LIMIT",
  "stop_price": "9.8",
  "operator": "LTE",
  "immediate_or_cancel": false,
  "post_only": true,
  "client_order_id": "",
  "created_at":"2019-01-29T06:05:56Z",
  "updated_at":"2019-01-29T06:05:56Z"
}]

Cancel Order

Notice: When canceling an order, if not found in opening orders, will return a NotFound error, Code: 10013

1. Cancel order by id in path:

POST /viewer/orders/{id}/cancel

Parameters

Name	Type	Require	Description	Example
id	number	true	order id

2. Cancel order by id or client_order_id in query:

POST /viewer/order/cancel

Parameters

Name	Type	Require	Description	Example
order_id	string	false	order id	10
client_order_id	string	false	client order id

Either order_id or client_order_id must be sent. If both order_id and client_order_id are provided, order_id takes precedence.

Response is Order object:

{
  "id": 10,
  "asset_pair_name": "EOS-BTC",
  "price": "10.00",
  "amount": "10.00",
  "filled_amount": "9.0",
  "avg_deal_price": "12.0",
  "side": "ASK",
  "state": "CANCELLED",
  "type": "STOP_LIMIT",
  "stop_price": "9.8",
  "operator": "LTE",
  "immediate_or_cancel": false,
  "post_only": true,
  "client_order_id": "",
  "created_at":"2019-01-29T06:05:56Z",
  "updated_at":"2019-01-29T06:05:56Z"
}

Cancel All Orders

POST /viewer/orders/cancel

Parameters

Name	Type	Require	Description	Example
asset_pair_name	string	true	asset pair name	BTC-USDT

Response example:

{
  "code":0,
  "data": {
    "cancelled":[
      58272370,
      58272377
    ],
    "failed":[]
  }
}