Orders
The Order endpoints allow your bot to enter, monitor and cancel orders directly.
- When entering an order, the bot can optionally provide a unique ID. In addition, once the order is accepted by the platform, a unique ID will be generated by BNF. Both IDs may be used to reference the order.
- The system may reject request if price is out of allowed range.
- The system checks precision of price and quantity fields to match the underlying exchange rules. When precision is too high, the values are automatically truncated.
- Symbol in the order request is the code of the market of the underlying exchange, as returned by the symbols endpoint.
[POST] orders/place
Description
Place an order on the platform.
Parameters
(Body)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| clientOrderId | string | Bot creator specified order ID | No |
| symbol | string | Symbol code as specified in the underlying exchange. E.g. BTCUSDT is BTC/USDT market in Binance. Symbol codes are also returned by the symbols endpoint. | Yes |
| side | string | Whether the order is a buy or sell order. Possible values: ‘BUY’ or ‘SELL’. | Yes |
| price | string | Limit price of the order. | Yes |
| quantity | string | Order starting value specified in absolute quantity of the market asset. Mutually exclusive with ‘quantityPct’. | Yes |
| quantityPct | string | Order starting quantity, percentage of available funds. This value is mutually exclusive with ‘quantity’. API uses specified percentage of free balance amount to place the order. | Yes |
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
| Name | Type | Description | Mandatory |
|---|---|---|---|
| clientOrderId | string | Client order ID specified by the bot creator for this order. | Yes |
| orderId | string | BNF generated order ID | Yes |
| createdTs | string | Creation timestamp of the order. | Yes |
[POST] orders/cancel
Description
Send a command to cancel an order.
The caller must specify ether orderId or clientOrderId.
Remark: Order cancellation is an asynchronous process. Depending on order state, it may take some time before cancelled state becomes visible. The system waits for all trades from the underlying exchange before order status is changed to CANCELED. This time is milliseconds under normal circumstances. Also see canceling flag in the order status.
Parameters
(Body)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| orderId | string | Optional order Id as generated by system when the order was placed. Either clientOrderId or orderId must be specified. | Yes* (or clientOrderId) |
| clientOrderId | string | Client order ID specified by the bot creator for this order. | Yes* (or orderId) |
| symbol | string | Symbol code as specified in underlying exchanged, returned by symbols endpoint. | Yes |
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
| Name | Type | Description | Mandatory |
|---|---|---|---|
| orderId | string | Order ID of the canceled order | Yes |
[GET] orders/status
Description
Get the status of an order. The caller must specify either orderId or clientOrderId.
The order should still be open or canceled/fulfilled but recently. The system can provide order information up to 24 hours after the order was closed. Older orders are not know to the system.
Parameters
(Query)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| orderId | string | Optional order Id as generated by system when the order was placed. Either clientOrderId or orderId must be specified. | Yes* (or clientOrderId) |
| clientOrderId | string | Client order ID specified by the bot creator for this order. | Yes* (or orderId) |
| symbol | string | Symbol code as specified in underlying exchanged, returned by symbols endpoint. | Yes |
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
| Name | Type | Description | Mandatory |
|---|---|---|---|
| orderId | string | Order ID generated by BNF. | Yes |
| clientOrderId | string | Optional order ID provided by the client when order was placed. | Yes |
| createdTs | string | Creation timestamp of the order. | Yes |
| side | string | Whether the order is a buy or sell order. Possible values: ‘BUY’ or ‘SELL’. | Yes |
| status | string | Order status. Remark: An order can be canceled both by the bot and also by the underlying exchange. The later looks like a spontaneous cancellation from the bot. Possible values: ‘OPEN’, ‘FULFILLED’, or ‘CANCELED’ | Yes |
| canceling | boolean | Cancel operation has been requested for the order. This property only makes sense for orders with status ‘OPEN’. | Yes |
| price | string | Limit price of the order. | Yes |
| quantity | string | Starting quantity of the order. | Yes |
| filled | string | Order amount that has already been filled. | Yes |
| remaining | string | Order amount that is still remaining to be filled. | Yes |
| trades | DtoTrade | Trades of the order. Values provided: ‘dateTime’ when the trade happened, ‘price’ of the trade, ‘quantity’ of the trade, and the ‘totalCost’ of the trade. | Yes |
[GET] orders/list-open
Description
Request the orders with the ‘OPEN’ status.
Parameters
(Query)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
Returns an array of orders that have the status ‘OPEN’. Data of each entry in the array is the same as the response of the orders/status endpoint.Trade Object
| Name | Type | Description | Mandatory |
|---|---|---|---|
| dateTime | string | Moment in time when the trade happened. | Yes |
| price | string | Order limit price | Yes |
| quantity | string | Starting quantity of the order | Yes |
| totalCost | string | Total cost of the trade. | Yes |
[GET] symbols
Description
Retrieves symbols available for trading.
Parameters
(Query)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
An array of symbols, for example "BTCUSDT".
[GET] balances
Description
Get detailed information about funds - available for trading, locked, borrowed, etc.
Parameters
(Query)
| Name | Type | Description | Mandatory |
|---|---|---|---|
| timestamp | string | The timestamp when request was prepared and sent. The timestamp is specified in ISO format and UTC timezone. Server rejects a request if the value is more than 5 seconds old. | Yes |
Response
| Name | Type | Description | Mandatory |
|---|---|---|---|
| assets | array | An array of asset balance objects. | Yes |
Asset Balance Object
| Name | Type | Description | Mandatory |
|---|---|---|---|
| asset | string | The exchange code of the asset, for example: ‘USDT’. | Yes |
| free | string | The amount of the asset that is free for trading. | Yes |
| locked | string | The amount of the asset that is locked for trading. | Yes |
| borrowed | string | The amount of the asset that has been borrowed (for shorting or leveraging purposes). | Yes |
| interest | string | The amount of interest that has accumulated for a borrowed asset. | Yes |
| netAsset | string | netAsset = free + locked - borrowed - interest | Yes |
API errors
API error json
json
{
"errorMessage": "error description",
"errorCode": 42,
"paramName": "invalid parameter name (optional)",
"paramValue": "invalid parameter value (optional)"
}
HTTP response codes
- 200 - Ok.
- 403 - Authentication error. Common reason: Request signature is not correct or request timestamp is too old.
- 4xx - Client side error. Common reason: Parameter validation errors. (See "paramName" and "paramValue" for parameter name/value).
- 5xx - Server side error.
API error codes
| Error code | Description |
|---|---|
| 42 - OTHER_ERROR | General error. (See "errorMessage" to find out a specific reason.) |
| 101 - NOT_ENOUGH_BALANCE | Balance is not enough to place an order. |
| 102 - MARKET_IS_INACTIVE | Market is currently inactive. |
| 103 - ORDER_CAN_NO_LONGER_BE_CANCELLED | Order is not open anymore so it can't be canceled. |
| 104 - ORDER_ALREADY_CANCELLED | Rarely seen error when order becomes canceled right before we cancel the order. |
| 105 - ORDER_ALREADY_REJECTED | Rarely seen error when order becomes rejected right before we cancel the order. |
| 106 - ORDER_ALREADY_FULFILLED | Rarely seen error when order becomes fulfilled right before we cancel the order. |
| 107 - PLACE_ORDER_IS_DISABLED | Maintenance: Market doesn't accept orders at the moment. |
| 108 - CANCEL_ORDER_IS_DISABLED | Maintenance: Market doesn't allow order to be canceled at the moment. |
| 201 - USER_NOT_FOUND | Unknown user. |
| 202 - ASSET_NOT_FOUND | Unknown asset. |
| 203 - EXCHANGE_SYMBOL_NOT_FOUND | Symbol is not available on the exchange. |
| 204 - TICKER_NOT_FOUND | Ticker is not available. |
| 205 - ORDER_NOT_FOUND | Order referred to in the request is not found. |
| 206 - INVALID_VALUE | General validation error. (See "errorMessage" to find out a specific reason.) |
| 207 - VALUE_TOO_LOW | Parameter value is below certain threshold. |
| 208 - VALUE_TOO_HIGH | Parameter value is above certain threshold. |
| 209 - CANNOT_EXTRACT_PARAM | Mandatory parameter is missing. Parameter format is not correct. |
| 210 - ORDER_DOES_NOT_BELONG_TO_USER | Order was placed on behalf of a different user. |
| 214 - CLIENT_ORDER_ID_IN_USE | Client order ID is not unique. |
| 215 - ORDER_VALUE_TOO_SMALL | Order notional value is less than 0.1 Euro. |
| 216 - EXCHANGE_NOT_FOUND | Unknown exchange. |
| 222 - SIGNAL_PROVIDER_NOT_FOUND | Unknown bot. |
| 225 - EXCHANGE_ASSET_NOT_FOUND | Asset is not available on the exchange. |
| 232 - DECIMAL_PRECISION_TOO_HIGH | Decimal parameter precision is too high. |
| 301 - FORBIDDEN | Insufficient permissions. |