HitBTC REST & Streaming API version 2.0 provides programmatic access to HitBTC’s next generation trading engine.
We strongly recommend using APIv2 for new users and switching to this newer version for our current traders to get the best trading experience.
Please find API version 1.0 here: APIv1 reference
By using HitBTC API you confirm that you have read and accept API License Agreement
- Development guide
- Best practices
- REST API Reference
- API Explorer
- Examples
- Market data
- Authentication
- Trading
- Trading history
- Account
- Socket API Reference
Environment | REST | Streaming |
---|---|---|
PROD | https://api.hitbtc.com/api/2 | wss:https://api.hitbtc.com/api/2/ws |
All timestamps are returned in ISO8601 format in UTC. Example: "2017-04-03T10:20:49.315Z"
All finance data, i.e. price, quantity, fee etc., should be arbitrary precision numbers and string representation. Example: "10.2000058"
Parameters:
Parameter | Description |
---|---|
limit | Number of results per call. Accepted values: 0 - 1000. Default 100 |
offset | Number of results offset. Default 0 |
sort | Sort direction. Accepted values: ASC, DESC. Default DESC |
by | Filtration definition. Accepted values: id, timestamp |
from | If filter by timestamp, then datetime. Otherwise object id |
till | If filter by timestamp, then datetime. Otherwise object id |
The HitBTC API development team strives to bring the best trading experience for our API users. Here is a set of best practices of using the API as efficiently as possible.
It keeps the underlying TCP connection active for multiple requests/responses. Subsequent requests will result in reduced latency as the TCP handshaking process is no longer required.
If you are using an HTTP 1.0 client, please ensure it supports the keep-alive directive and submit the header Connection: Keep-Alive with your request.
Keep-Alive is a part of the protocol in HTTP 1.1 and enabled by default on compliant clients. However, you will have to ensure your implementation does not set the connection header to other values.
Use Streaming API for real time updates of your orders and trades and any transactions changes.
- 200 OK Successful request
- 400 Bad Request. Returns JSON with the error message
- 401 Unauthorized. Authorisation required or failed
- 403 Forbidden. Action is forbidden for API key
- 429 Too Many Requests. Your connection is being rate-limited
- 500 Internal Server. Internal Server Error
- 503 Service Unavailable. Service is down for maintenance
- 504 Gateway Timeout. Request timeout expired
All error responses have error code
and human readable message
fields. Some errors contain additional description
field.
Example error response:
{
"error": {
"code": 20001,
"message": "Insufficient funds",
"description": "Check that the funds are sufficient, given commissions"
}
}
List of errors
Error code | HTTP Status Code | Message | Note |
---|---|---|---|
403 | 401 | Action is forbidden for account | |
429 | 429 | Too many requests | Action is being rate limited for account |
500 | 500 | Internal Server Error | |
503 | 503 | Service Unavailable | Try it again later |
504 | 504 | Gateway Timeout | Check the result of your request later |
1001 | 401 | Authorisation required | |
1002 | 401 | Authorisation failed | |
1003 | 403 | Action is forbidden for this API key | Check permissions for API key |
1004 | 401 | Unsupported authorisation method | Use Basic authentication |
2001 | 400 | Symbol not found | |
2002 | 400 | Currency not found | |
20001 | 400 | Insufficient funds | Insufficient funds for creating order or any account operation |
20002 | 400 | Order not found | Attempt to get active order that not existing, filled, canceled or expired. Attempt to cancel not existing order. Attempt to cancel already filled or expired order. |
20003 | 400 | Limit exceeded | Withdrawal limit exceeded |
20004 | 400 | Transaction not found | Requested transaction not found |
20005 | 400 | Payout not found | |
20006 | 400 | Payout already committed | |
20007 | 400 | Payout already rolled back | |
20008 | 400 | Duplicate clientOrderId | |
10001 | 400 | Validation error | Input not valid, see more in message field |
You can explore API using SwaggerUI (https://api.hitbtc.com/api/2/explore/)
- Python rest example example_rest.py
GET /api/2/public/currency
GET /api/2/public/currency/{currency}
Return the actual list of available currencies, tokens, ICO etc.
Responses:
Name | Type | Description |
---|---|---|
id | String | Currency identifier. In the future, the description will simply use the currency |
fullName | String | Currency full name |
crypto | Boolean | Is currency belongs to blockchain (false for ICO and fiat, like EUR) |
payinEnabled | Boolean | Is allowed for deposit (false for ICO) |
payinPaymentId | Boolean | Is required to provide additional information other than the address for deposit |
payinConfirmations | Number | Blocks confirmations count for deposit |
payoutEnabled | Boolean | Is allowed for withdraw (false for ICO) |
payoutIsPaymentId | Boolean | Is allowed to provide additional information for withdraw |
transferEnabled | Boolean | Is allowed to transfer between trading and account (may be disabled on maintain) |
Example data:
[
{
"id": "BTC",
"fullName": "Bitcoin",
"crypto": true,
"payinEnabled": true,
"payinPaymentId": false,
"payinConfirmations": 2,
"payoutEnabled": true,
"payoutIsPaymentId": false,
"transferEnabled": true
},
{
"id": "ETH",
"fullName": "Ethereum",
"crypto": true,
"payinEnabled": true,
"payinPaymentId": false,
"payinConfirmations": 2,
"payoutEnabled": true,
"payoutIsPaymentId": false,
"transferEnabled": true
}
]
GET /api/2/public/symbol
GET /api/2/public/symbol/{symbol}
Return the actual list of currency symbols (currency pairs) traded on HitBTC exchange. The first listed currency of a symbol is called the base currency, and the second currency is called the quote currency. The currency pair indicates how much of the quote currency is needed to purchase one unit of the base currency. Read more
Responses:
Name | Type | Description |
---|---|---|
id | String | Symbol identifier. In the future, the description will simply use the symbol |
baseCurrency | String | |
quoteCurrency | String | |
quantityIncrement | Number | |
tickSize | Number | |
takeLiquidityRate | Number | Default fee rate |
provideLiquidityRate | Number | Default fee rate for market making trades |
feeCurrency | String |
Example data:
[
{
"id": "ETHBTC",
"baseCurrency": "ETH",
"quoteCurrency": "BTC",
"quantityIncrement": "0.001",
"tickSize": "0.000001",
"takeLiquidityRate": "0.001",
"provideLiquidityRate": "-0.0001",
"feeCurrency": "BTC"
}
]
GET /api/2/public/ticker
GET /api/2/public/ticker/{symbol}
Return ticker information
Responses:
Name | Type | Description |
---|---|---|
ask | Number | Best ask price |
bid | Number | Best bid price |
last | Number | Last trade price |
open | Number | Last trade price 24 hours ago |
low | Number | Lowest trade price within 24 hours |
high | Number | Highest trade price within 24 hours |
volume | Number | Total trading amount within 24 hours in base currency |
volumeQuote | Number | Total trading amount within 24 hours in quote currency |
timestamp | Datetime | Last update or refresh ticker timestamp |
symbol | String |
Example data:
[
{
"ask": "0.050043",
"bid": "0.050042",
"last": "0.050042",
"open": "0.047800",
"low": "0.047052",
"high": "0.051679",
"volume": "36456.720",
"volumeQuote": "1782.625000",
"timestamp": "2017-05-12T14:57:19.999Z",
"symbol": "ETHBTC"
}
]
GET /api/2/public/trades/{symbol}
Parameters:
Name | Type | Description |
---|---|---|
sort | String | Default DESC |
by | String | Filtration definition. Accepted values: id, timestamp. Default timestamp |
from | Number or Datetime | |
till | Number or Datetime | |
limit | Number | |
offset | Number |
Responses:
Name | Type | Description |
---|---|---|
id | Number | Trade id |
price | Number | Trade price |
quantity | Number | Trade quantity |
side | String | Trade side sell or buy |
timestamp | Datetime | Trade timestamp |
Example response:
[
{
"id": 9533117,
"price": "0.046001",
"quantity": "0.220",
"side": "sell",
"timestamp": "2017-04-14T12:18:40.426Z"
},
{
"id": 9533116,
"price": "0.046002",
"quantity": "0.022",
"side": "buy",
"timestamp": "2017-04-14T11:56:37.027Z"
}
]
GET /api/2/public/orderbook/{symbol}
An order book is an electronic list of buy and sell orders for a specific symbol, organized by price level.
Parameters:
Name | Type | Description |
---|---|---|
limit | Number | Limit of orderbook levels, default 100. Set 0 to view full orderbook levels |
Responses:
Name | Type | Description |
---|---|---|
ask | Array | Ask side array of levels |
bid | Array | Bid side array of levels |
size | Number | Total volume of orders with the specified price |
price | Number | Price level |
Example response:
{
"ask": [
{
"price": "0.046002",
"size": "0.088"
},
{
"price": "0.046800",
"size": "0.200"
}
],
"bid": [
{
"price": "0.046001",
"size": "0.005"
},
{
"price": "0.046000",
"size": "0.200"
}
]
}
GET /api/2/public/candles/{symbol}
An candles used for OHLC a specific symbol.
Parameters:
Name | Type | Description |
---|---|---|
limit | Number | Limit of candles, default 100. |
period | String | One of: M1 (one minute), M3, M5, M15, M30, H1, H4, D1, D7, 1M (one month). Default is M30 (30 minutes). |
Responses:
Name | Type | Description |
---|---|---|
timestamp | Datetime | |
open | Number | Open price |
close | Number | Close price |
min | Number | Min price |
max | Number | Max price |
volume | Number | Volume in base currency |
volumeQuote | Number | Volume in quote currency |
Result contain candles only with non zero volume
Example response:
[
{
"timestamp": "2017-10-20T20:00:00.000Z",
"open": "0.050459",
"close": "0.050087",
"min": "0.050000",
"max": "0.050511",
"volume": "1326.628",
"volumeQuote": "66.555987736"
},
{
"timestamp": "2017-10-20T20:30:00.000Z",
"open": "0.050108",
"close": "0.050139",
"min": "0.050068",
"max": "0.050223",
"volume": "87.515",
"volumeQuote": "4.386062831"
}
]
Public market data available without authentication, for other requests authentication is required.
You should create API keys on HitBTC API Setting page. You can create multiple API keys with different permissions for your applications.
Use Basic Authentication to access REST API.
Example:
curl -u "publicKey:secret" https://api.hitbtc.com/api/2/trading/balance
GET /api/2/trading/balance
Responses:
Name | Type | Description |
---|---|---|
currency | String | |
available | Number | Amount available for trading or transfer to main account |
reserved | Number | Amount reserved for active orders or incomplete transfers to main account |
Example response:
[
{
"currency": "ETH",
"available": "10.000000000",
"reserved": "0.560000000"
},
{
"currency": "BTC",
"available": "0.010205869",
"reserved": "0"
}
]
Curl example:
curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" "https://api.hitbtc.com/api/2/trading/balance"
Python 3 example:
import requests
r = requests.get('https://api.hitbtc.com/api/2/trading/balance', auth=('ff20f250a7b3a414781d1abe11cd8cee', 'fb453577d11294359058a9ae13c94713'))
print(r.json())
Order model:
Name | Type | Description |
---|---|---|
id | Number | Unique identifier for Order as assigned by exchange |
clientOrderId | String | Unique identifier for Order as assigned by trader. Uniqueness must be guaranteed within a single trading day, including all active orders. |
symbol | String | Trading symbol |
side | String | sell buy |
status | String | new, suspended, partiallyFilled, filled, canceled, expired |
type | String | Enum: limit, market, stopLimit, stopMarket |
timeInForce | String | Time in force is a special instruction used when placing a trade to indicate how long an order will remain active before it is executed or expires GTC - Good till cancel. GTC order won't close until it is filled. IOC - An immediate or cancel order is an order to buy or sell that must be executed immediately, and any portion of the order that cannot be immediately filled is cancelled. FOK - Fill or kill is a type of time-in-force designation used in securities trading that instructs a brokerage to execute a transaction immediately and completely or not at all. Day - keeps the order active until the end of the trading day in UTC. GTD - Good till date specified in expireTime . |
quantity | Number | Order quantity |
price | Number | Order price |
cumQuantity | Number | Cumulative executed quantity |
createdAt | Datetime | |
updatedAt | Datetime | |
stopPrice | Number | |
expireTime | Datetime |
GET /api/2/order
Return array of active orders.
Parameters:
Name | Type | Description |
---|---|---|
symbol | String | Optional parameter to filter active orders by symbol |
Response: Array of orders
Example response:
[
{
"id": 840450210,
"clientOrderId": "c1837634ef81472a9cd13c81e7b91401",
"symbol": "ETHBTC",
"side": "buy",
"status": "partiallyFilled",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.020",
"price": "0.046001",
"cumQuantity": "0.005",
"createdAt": "2017-05-12T17:17:57.437Z",
"updatedAt": "2017-05-12T17:18:08.610Z"
}
]
GET /api/2/order/{clientOrderId}
Parameters:
Name | Type | Description |
---|---|---|
wait | Number | Optional parameter. Time in milliseconds. Max 60000. Default none. Use long polling request, if order is filled, canceled or expired return order info instantly, or after specified wait time returns actual order info |
Response: Order
Example response:
{
"id": 840450210,
"clientOrderId": "c1837634ef81472a9cd13c81e7b91401",
"symbol": "ETHBTC",
"side": "buy",
"status": "partiallyFilled",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.020",
"price": "0.046001",
"cumQuantity": "0.005",
"createdAt": "2017-05-12T17:17:57.437Z",
"updatedAt": "2017-05-12T17:18:08.610Z"
}
POST /api/2/order
PUT /api/2/order/{clientOrderId}
Price accuracy and quantity.
Symbol config contain tickSize
parameter which means that price
should be divide by tickSize
without residue. Quantity
should be divide by quantityIncrement
without residue. By default, if strictValidate
not enabled, server round half down price
and quantity
for tickSize
and quantityIncrement
.
Example for ETHBTC: tickSize
= '0.000001' then price '0.046016' - valid, '0.0460165' - invalid
Fees
Fee charged in symbol feeCurrency
. Maker-taker fees offer a transaction rebate provideLiquidityRate
to those who provide liquidity (the market maker), while charging customers who take that liquidity takeLiquidityRate
.
For buy orders you must have enough available balance including fees. Available balance > price * quantity * (1 + takeLiquidityRate)
Result order status
For orders with timeInForce
IOC
or FOK
REST API returns final order state: filled or expired.
If order can be instantly executed, then REST API return filled or partiallyFilled order's info.
Parameters:
Name | Type | Description |
---|---|---|
clientOrderId | String | Optional parameter, if skipped - will be generated by server. Uniqueness must be guaranteed within a single trading day, including all active orders. |
symbol | String | Trading symbol |
side | String | sell buy |
type | String | Optional. Default - limit. One of: limit, market, stopLimit, stopMarket |
timeInForce | String | Optional. Default - GDC. One of: GTC, IOC, FOK, Day, GTD |
quantity | Number | Order quantity |
price | Number | Order price. Required for limit types. |
stopPrice | Number | Required for stop types. |
expireTime | Datetime | Required for GTD timeInForce. |
strictValidate | Boolean | Price and quantity will be checked that they increment within tick size and quantity step. See symbol tickSize and quantityIncrement |
Response: Order
Python 3 example:
import requests
orderData = {'symbol':'ethbtc', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }
r = requests.post('https://api.hitbtc.com/api/2/order', data = orderData, auth=('ff20f250a7b3a414781d1abe11cd8cee', 'fb453577d11294359058a9ae13c94713'))
print(r.json())
> {'id': 0, 'side': 'sell', 'clientOrderId': 'd8574207d9e3b16a4a5511753eeef175', 'updatedAt': '2017-05-15T17:01:05.092Z', 'symbol': 'ETHBTC', 'type': 'limit', 'quantity': '0.063', 'price': '0.046016', 'status': 'new', 'cumQuantity': '0.000', 'createdAt': '2017-05-15T17:01:05.092Z', 'timeInForce': 'GTC'}
Example success created response:
{
"id": 0,
"clientOrderId": "d8574207d9e3b16a4a5511753eeef175",
"symbol": "ETHBTC",
"side": "sell",
"status": "new",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.063",
"price": "0.046016",
"cumQuantity": "0.000",
"createdAt": "2017-05-15T17:01:05.092Z",
"updatedAt": "2017-05-15T17:01:05.092Z"
}
Example error Insufficient funds response:
{
"error": {
"code": 20001,
"message": "Insufficient funds",
"description": "Check that the funds are sufficient, given commissions"
}
}
DELETE /api/2/order
Cancel all active orders, or all active orders for specified symbol.
Parameters:
Name | Type | Description |
---|---|---|
symbol | String | Optional parameter to filter active orders by symbol |
Response: Array of Orders
DELETE /api/2/order/{clientOrderId}
Response: Order
Example response:
{
"id": 0,
"clientOrderId": "d8574207d9e3b16a4a5511753eeef175",
"symbol": "ETHBTC",
"side": "sell",
"status": "canceled",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.000",
"price": "0.046016",
"cumQuantity": "0.000",
"createdAt": "2017-05-15T17:01:05.092Z",
"updatedAt": "2017-05-15T18:08:57.226Z"
}
Example error Order not found response:
{
"error": {
"code": 20002,
"message": "Order not found",
"description": ""
}
}
GET /api/2/trading/fee/{symbol}
Get personal trading commission rate.
Example response:
{
"takeLiquidityRate": "0.001",
"provideLiquidityRate": "-0.0001"
}
Please note, that trading history may be updated with delay up to 30 seconds, with mean delay around 1 second.
GET /api/2/history/order
All orders older then 24 hours without trades are deleted.
Parameters:
Name | Type | Description |
---|---|---|
symbol | String | Optional parameter to filter active orders by symbol |
clientOrderId | String | If set, other parameters will be ignored. Without limit and pagination |
from | Datetime | |
till | Datetime | |
limit | Number | Default 100 |
offset | Number |
Response: Array of Orders
GET /api/2/history/trades
Parameters:
Name | Type | Description |
---|---|---|
symbol | String | Optional parameter to filter active orders by symbol |
sort | String | DESC or ASC . Default value DESC |
by | String | timestamp by default, or id |
from | Datetime or Number | |
till | Datetime or Number | |
limit | Number | Default 100 |
offset | Number |
Responses:
Name | Type | Description |
---|---|---|
id | Number | Unique identifier for Trade as assigned by exchange |
orderId | Number | Unique identifier for Order as assigned by exchange |
clientOrderId | String | Unique identifier for Order as assigned by trader. |
symbol | String | Trading symbol |
side | String | sell buy |
quantity | Number | Trade quantity |
price | Number | Trade price |
fee | Number | Trade commission. Could be negative – reward. Fee currency see in symbol config |
timestamp | Datetime | Trade timestamp |
Example response:
[
{
"id": 9535486,
"clientOrderId": "f8dbaab336d44d5ba3ff578098a68454",
"orderId": 816088377,
"symbol": "ETHBTC",
"side": "sell",
"quantity": "0.061",
"price": "0.045487",
"fee": "0.000002775",
"timestamp": "2017-05-17T12:32:57.848Z"
},
{
"id": 9535437,
"clientOrderId": "27b9bfc068b44194b1f453c7af511ed6",
"orderId": 816088021,
"symbol": "ETHBTC",
"side": "buy",
"quantity": "0.038",
"price": "0.046000",
"fee": "-0.000000174",
"timestamp": "2017-05-17T12:30:57.848Z"
}
]
GET /api/2/history/order/{orderId}/trades
Parameters:
Name | Type | Description |
---|---|---|
orderId | Number | Order id |
Provide order id, because clientOrderId can be not uniq during long period.
Responses:
Name | Type | Description |
---|---|---|
id | Number | Unique identifier for Trade as assigned by exchange |
orderId | Number | Unique identifier for Order as assigned by exchange |
clientOrderId | String | Unique identifier for Order as assigned by trader. |
symbol | String | Trading symbol |
side | String | sell buy |
quantity | Number | Trade quantity |
price | Number | Trade price |
fee | Number | Trade commission. Could be negative – reward. Fee currency see in symbol config |
timestamp | Datetime | Trade timestamp |
GET /api/2/account/balance
Responses:
Name | Type | Description |
---|---|---|
currency | String | |
available | Number | Amount available for withdraw or transfer to trading account |
reserved | Number | Amount reserved for incomplete transactions |
Response example:
[
{
"currency": "BTC",
"available": "0.0504600",
"reserved": "0.0000000"
},
{
"currency": "ETH",
"available": "30.8504600",
"reserved": "0.0000000"
}
]
GET /api/2/account/crypto/address/{currency}
- Get current address
POST /api/2/account/crypto/address/{currency}
- Create new address
Responses:
Name | Type | Description |
---|---|---|
address | String | Address for deposit |
paymentId | String | Optional additional parameter. Required for deposit if persist |
Response example:
{
"address": "NXT-G22U-BYF7-H8D9-3J27W",
"paymentId": "616598347865"
}
POST /api/2/account/crypto/withdraw
Parameters:
Name | Type | Description |
---|---|---|
currency | String | Currency |
amount | Number | The amount that will be sent to the specified address |
address | String | |
paymentId | String | Optional parameter |
networkFee | Number or String | Optional parameter. Too low and too high commission value will be rounded to valid values. |
includeFee | Boolean | Default false. If set true then total will be spent the specified amount, fee and networkFee will be deducted from the amount |
autoCommit | Boolean | Default true. If set false then you should commit or rollback transaction in an hour. Used in two phase commit schema. |
Responses:
Name | Type | Description |
---|---|---|
id | String | Unique identifier for Transaction as assigned by exchange |
Response example:
{
"id": "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
}
PUT /api/2/account/crypto/withdraw/{id}
- Commit
DELETE /api/2/account/crypto/withdraw/{id}
- Rollback
Both methods idempotent
Responses:
Name | Type | Description |
---|---|---|
result | Boolean | True of request completed |
Response example:
{
"result": true
}
POST /api/2/account/transfer
Parameters:
Name | Type | Description |
---|---|---|
currency | String | Currency |
amount | Number | The amount that will transfer between balances |
type | String | bankToExchange or exchangeToBank |
Responses:
Name | Type | Description |
---|---|---|
id | String | Unique identifier for Transaction as assigned by exchange |
Response example:
{
"id": "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
}
GET /api/2/account/transactions
GET /api/2/account/transactions/{id}
- get transaction by transaction id
Parameters:
Name | Type | Description |
---|---|---|
currency | String | Currency |
sort | String | DESC or ASC . Default value DESC |
by | String | timestamp or index . Default value timestamp |
from | Datetime or Number | If sort by timestamp then Datetime, otherwise Number of index value |
till | Datetime or Number | If sort by timestamp then Datetime, otherwise Number of index value |
limit | Number | Default 100 |
offset | Number |
Responses:
Name | Type | Description |
---|---|---|
id | String | Unique identifier for Transaction as assigned by exchange |
index | Number | Is the internal index value that represents when the entry was updated |
currency | String | Currency |
amount | Number | |
fee | Number | |
networkFee | Number | |
address | String | |
paymentId | String | |
hash | String | Transaction hash |
status | String | pending, failed, success |
type | String | One of: payout - crypto withdraw transaction, payin - crypto deposit transaction, deposit, withdraw, bankToExchange, exchangeToBank |
createdAt | Datetime | |
updatedAt | Datetime |
Example response:
[
{
"id": "6a2fb54d-7466-490c-b3a6-95d8c882f7f7",
"index": 20400458,
"currency": "ETH",
"amount": "38.616700000000000000000000",
"fee": "0.000880000000000000000000",
"networkFee": "0.000420000000000000000000",
"address": "0xfaEF4bE10dDF50B68c220c9ab19381e20B8EEB2B",
"hash": "eece4c17994798939cea9f6a72ee12faa55a7ce44860cfb95c7ed71c89522fe8",
"status": "pending",
"type": "payout",
"createdAt": "2017-05-18T18:05:36.957Z",
"updatedAt": "2017-05-18T19:21:05.370Z"
}
]
Use JSON-RPC 2.0 over WebSocket connection as transport.
A rpc call is represented by sending a Request object to a Server.
The Request object has the following members:
- method - A String containing the name of the method to be invoked.
- params - A Structured value that holds the parameter values to be used during the invocation of the method.
- id - An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null.
A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client.
The Notification object has the following members:
- method - A String containing the name of the method to be invoked.
- params - A Structured value that holds the parameter values to be used during the invocation of the method.
When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications.
The Response is expressed as a single JSON Object, with the following members:
- result - This member is REQUIRED on success. This member MUST NOT exist if there was an error invoking the method. The value of this member is determined by the method invoked on the Server.
- error - This member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during invocation. The value for this member MUST be an Object as defined in section Error response
The parameters of requests, responses, and errors correspond to REST, but usage flow differ. First you should subscribe for interested data. Then server send full snapshot of data, after that server send update notification.
Server response for every request. On success subscription response is true. Example:
{
"jsonrpc": "2.0",
"result": true,
"id": 123
}
Request:
Methods: getCurrencies,getCurrency
Example:
{
"method": "getCurrency",
"params": {
"currency": "ETH"
},
"id": 123
}
Response
Example:
{
"jsonrpc": "2.0",
"result": {
"id": "ETH",
"fullName": "Ethereum",
"crypto": true,
"payinEnabled": true,
"payinPaymentId": false,
"payinConfirmations": 2,
"payoutEnabled": true,
"payoutIsPaymentId": false,
"transferEnabled": true
},
"id": 123
}
Request
Methods: getSymbols,getSymbol
Example:
{
"method": "getSymbol",
"params": {
"symbol": "ETHBTC"
},
"id": 123
}
Response
Example:
{
"jsonrpc": "2.0",
"result": {
"id": "ETHBTC",
"baseCurrency": "ETH",
"quoteCurrency": "BTC",
"quantityIncrement": "0.001",
"tickSize": "0.000001",
"takeLiquidityRate": "0.001",
"provideLiquidityRate": "-0.0001",
"feeCurrency": "BTC"
},
"id": 123
}
Request:
Methods: subscribeTicker, unsubscribeTicker
Example:
{
"method": "subscribeTicker",
"params": {
"symbol": "ETHBTC"
},
"id": 123
}
Notification:
Method: ticker
Example:
{
"jsonrpc": "2.0",
"method": "ticker",
"params": {
"ask": "0.054464",
"bid": "0.054463",
"last": "0.054463",
"open": "0.057133",
"low": "0.053615",
"high": "0.057559",
"volume": "33068.346",
"volumeQuote": "1832.687530809",
"timestamp": "2017-10-19T15:45:44.941Z",
"symbol": "ETHBTC"
}
}
Request
Methods: subscribeOrderbook, unsubscribeOrderbook
Example:
{
"method": "subscribeOrderbook",
"params": {
"symbol": "ETHBTC"
},
"id": 123
}
Notification snapshot
Message contains a full snapshot of order book.
Method: snapshotOrderbook
Example:
{
"jsonrpc": "2.0",
"method": "snapshotOrderbook",
"params": {
"ask": [
{
"price": "0.054588",
"size": "0.245"
},
{
"price": "0.054590",
"size": "0.000"
},
{
"price": "0.054591",
"size": "2.784"
},
{
"price": "0.054592",
"size": "35.000"
},
{
"price": "0.054595",
"size": "20.000"
},
{
"price": "0.054600",
"size": "0.030"
}
],
"bid": [
{
"price": "0.054558",
"size": "0.500"
},
{
"price": "0.054557",
"size": "0.076"
},
{
"price": "0.054524",
"size": "7.725"
},
{
"price": "0.054523",
"size": "0.522"
},
{
"price": "0.054520",
"size": "20.000"
}
],
"symbol": "ETHBTC",
"sequence": 8073827
}
}
Notification update
Message contains incremental changes
size = 0 means that level was deleted
sequence is monotone increasing for each update, each symbol has its own sequence
Method: updateOrderbook
Example:
{
"jsonrpc": "2.0",
"method": "updateOrderbook",
"params": {
"ask": [
{
"price": "0.054590",
"size": "0.000"
},
{
"price": "0.054591",
"size": "0.000"
},
{
"price": "0.054639",
"size": "2.113"
}
],
"bid": [
{
"price": "0.054521",
"size": "2.887"
},
{
"price": "0.054504",
"size": "0.000"
}
],
"symbol": "ETHBTC",
"sequence": 8073830
}
}
Request
Methods: subscribeTrades, unsubscribeTrades
Example:
{
"method": "subscribeTrades",
"params": {
"symbol": "ETHBTC"
},
"id": 123
}
Notification
Method: snapshotTrades
Example:
{
"jsonrpc": "2.0",
"method": "snapshotTrades",
"params": {
"data": [
{
"id": 54469456,
"price": "0.054656",
"quantity": "0.057",
"side": "buy",
"timestamp": "2017-10-19T16:33:42.821Z"
},
{
"id": 54469497,
"price": "0.054656",
"quantity": "0.092",
"side": "buy",
"timestamp": "2017-10-19T16:33:48.754Z"
},
{
"id": 54469697,
"price": "0.054669",
"quantity": "0.002",
"side": "buy",
"timestamp": "2017-10-19T16:34:13.288Z"
}
],
"symbol": "ETHBTC"
}
}
Notification update
Method: updateTrades
Example:
{
"jsonrpc": "2.0",
"method": "updateTrades",
"params": {
"data": [
{
"id": 54469813,
"price": "0.054670",
"quantity": "0.183",
"side": "buy",
"timestamp": "2017-10-19T16:34:25.041Z"
}
],
"symbol": "ETHBTC"
}
}
Request
Method: getTrades
Use use the same parameters as for REST
Example:
{
"method": "getTrades",
"params": {
"symbol": "ETHBTC",
"limit": 3,
"sort": "DESC",
"by": "id"
},
"id": 123
}
Response
Example:
{
"jsonrpc": "2.0",
"result": {
"data": [
{
"id": 54472171,
"price": "0.054443",
"quantity": "2.213",
"side": "sell",
"timestamp": "2017-10-19T16:39:20.796Z"
},
{
"id": 54472170,
"price": "0.054453",
"quantity": "0.030",
"side": "sell",
"timestamp": "2017-10-19T16:39:20.796Z"
},
{
"id": 54472169,
"price": "0.054454",
"quantity": "0.052",
"side": "sell",
"timestamp": "2017-10-19T16:39:20.796Z"
}
],
"symbol": "ETHBTC"
},
"id": 123
}
Request
Method: subscribeCandles, unsubscribeCandles
Params:
Example:
{
"method": "subscribeCandles",
"params": {
"symbol": "ETHBTC",
"period": "M30"
},
"id": 123
}
Notification snapshot
Method: snapshotCandles
Example:
{
"jsonrpc": "2.0",
"method": "snapshotCandles",
"params": {
"data": [
{
"timestamp": "2017-10-19T15:00:00.000Z",
"open": "0.054801",
"close": "0.054625",
"min": "0.054601",
"max": "0.054894",
"volume": "380.750",
"volumeQuote": "20.844237223"
},
{
"timestamp": "2017-10-19T15:30:00.000Z",
"open": "0.054616",
"close": "0.054618",
"min": "0.054420",
"max": "0.054724",
"volume": "348.527",
"volumeQuote": "19.011854364"
},
{
"timestamp": "2017-10-19T16:00:00.000Z",
"open": "0.054587",
"close": "0.054626",
"min": "0.054408",
"max": "0.054768",
"volume": "194.014",
"volumeQuote": "10.595416973"
},
{
"timestamp": "2017-10-19T16:30:00.000Z",
"open": "0.054614",
"close": "0.054443",
"min": "0.054339",
"max": "0.054724",
"volume": "141.213",
"volumeQuote": "7.706358298"
}
],
"symbol": "ETHBTC",
"period": "M30"
}
}
Notification update
Method: updateCandles
Example:
{
"jsonrpc": "2.0",
"method": "updateCandles",
"params": {
"data": [
{
"timestamp": "2017-10-19T16:30:00.000Z",
"open": "0.054614",
"close": "0.054465",
"min": "0.054339",
"max": "0.054724",
"volume": "141.268",
"volumeQuote": "7.709353873"
}
],
"symbol": "ETHBTC",
"period": "M30"
}
}
You should authentication session once before request requires authorisation.
Request
Method: login
Params:
Name | Type | Description |
---|---|---|
algo | String | "BASIC" or "HS256" |
pKey | String | API public key |
sKey | String | API secret key, required on BASIC algo |
nonce | String | Random string, required on HS256 algo |
signature | String | HMAC SHA256 sign nonce with API secret key, required on HS256 algo |
Example BASIC:
{
"method": "login",
"params": {
"algo": "BASIC",
"pKey": "3ef4a9f8c8bf04bd8f09884b98403eae",
"sKey": "2deb570ab58fd553a4ed3ee249fd2d51"
}
}
Example HS256:
{
"method": "login",
"params": {
"algo": "HS256",
"pKey": "3ef4a9f8c8bf04bd8f09884b98403eae",
"nonce": "N1g287gL8YOwDZr",
"signature": "b1c0ae399c2d341866a214f7d3ed755b821c1c36fc6f17083ef05fbb55b7f986"
}
}
Trade via socket have powerful changes to compared with REST:
- Fast - time to place new order a bit higher than network latency.
- Server notify on any order updates.
- FIFO. Your requests execute in requested order.
Request:
Method: subscribeReports
Example:
{
"method": "subscribeReports",
"params": {}
}
Notification snapshot:
Notification with active orders send after subscription or on any service maintain.
Method: activeOrders
Example:
{
"jsonrpc": "2.0",
"method": "activeOrders",
"params": [
{
"id": "4345613661",
"clientOrderId": "57d5525562c945448e3cbd559bd068c3",
"symbol": "BCCBTC",
"side": "sell",
"status": "new",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.013",
"price": "0.100000",
"cumQuantity": "0.000",
"createdAt": "2017-10-20T12:17:12.245Z",
"updatedAt": "2017-10-20T12:17:12.245Z",
"reportType": "status"
}
]
}
Notification report
Method: report
Params:
Name | Type | Description |
---|---|---|
id | Number | Unique identifier for Order as assigned by exchange |
clientOrderId | String | Unique identifier for Order as assigned by trader. |
symbol | String | Trading symbol |
side | String | sell or buy |
status | String | new, suspended, partiallyFilled, filled, canceled, expired |
type | String | Enum: limit, market, stopLimit, stopMarket |
timeInForce | String | Time in force is a special instruction used when placing a trade to indicate how long an order will remain active before it is executed or expires GTC - Good till cancel. GTC order won't close until it is filled. IOC - An immediate or cancel order is an order to buy or sell that must be executed immediately, and any portion of the order that cannot be immediately filled is cancelled. FOK - Fill or kill is a type of time-in-force designation used in securities trading that instructs a brokerage to execute a transaction immediately and completely or not at all. Day - keeps the order active until the end of the trading day in UTC. GTD - Good till date specified in expireTime . |
quantity | Number | Order quantity |
price | Number | Order price |
cumQuantity | Number | Cumulative executed quantity |
createdAt | Datetime | |
updatedAt | Datetime | |
stopPrice | Number | |
expireTime | Datetime | |
reportType | String | One of: status, new, canceled, expired, suspended, trade, replaced |
tradeId | Number | Required for reportType = trade. Trade Id. |
tradeQuantity | Number | Required for reportType = trade. Quantity of trade. |
tradePrice | Number | Required for reportType = trade. Trade price. |
tradeFee | Number | Required for reportType = trade. Fee paid for trade. |
originalRequestClientOrderId | String | Identifier of replaced order. |
Example:
{
"jsonrpc": "2.0",
"method": "report",
"params": {
"id": "4345697765",
"clientOrderId": "53b7cf917963464a811a4af426102c19",
"symbol": "ETHBTC",
"side": "sell",
"status": "filled",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.001",
"price": "0.053868",
"cumQuantity": "0.001",
"createdAt": "2017-10-20T12:20:05.952Z",
"updatedAt": "2017-10-20T12:20:38.708Z",
"reportType": "trade",
"tradeQuantity": "0.001",
"tradePrice": "0.053868",
"tradeId": 55051694,
"tradeFee": "-0.000000005"
}
}
Method: newOrder
Params:
Name | Type | Description |
---|---|---|
clientOrderId | String | Required parameter. Uniqueness must be guaranteed within a single trading day, including all active orders. |
symbol | String | Trading symbol |
side | String | sell buy |
type | String | Optional. Default - limit. One of: limit, market, stopLimit, stopMarket |
timeInForce | String | Optional. Default - GDC. One of: GTC, IOC, FOK, Day, GTD |
quantity | Number | Order quantity |
price | Number | Order price. Required for limit types. |
stopPrice | Number | Required for stop types. |
expireTime | Datetime | Required for GTD timeInForce. |
strictValidate | Boolean | Price and quantity will be checked that they increment within tick size and quantity step. See symbol tickSize and quantityIncrement |
Example:
{
"method": "newOrder",
"params": {
"clientOrderId": "57d5525562c945448e3cbd559bd068c4",
"symbol": "ETHBTC",
"side": "sell",
"price": "0.059837",
"quantity": "0.015"
},
"id": 123
}
Example error response:
{
"jsonrpc": "2.0",
"error": {
"code": 20001,
"message": "Insufficient funds",
"description": "Check that the funds are sufficient, given commissions"
},
"id": 123
}
Example success response:
{
"jsonrpc": "2.0",
"result": {
"id": "4345947689",
"clientOrderId": "57d5525562c945448e3cbd559bd068c4",
"symbol": "ETHBTC",
"side": "sell",
"status": "new",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.001",
"price": "0.093837",
"cumQuantity": "0.000",
"createdAt": "2017-10-20T12:29:43.166Z",
"updatedAt": "2017-10-20T12:29:43.166Z",
"reportType": "new"
},
"id": 123
}
Notification
report
will arrived before request result
Method: cancelOrder
Example:
{
"method": "cancelOrder",
"params": {
"clientOrderId": "57d5525562c945448e3cbd559bd068c4"
},
"id": 123
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"id": "4345947689",
"clientOrderId": "57d5525562c945448e3cbd559bd068c4",
"symbol": "ETHBTC",
"side": "sell",
"status": "canceled",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.001",
"price": "0.093837",
"cumQuantity": "0.000",
"createdAt": "2017-10-20T12:29:43.166Z",
"updatedAt": "2017-10-20T12:31:26.174Z",
"reportType": "canceled"
},
"id": 123
}
The order cancel/replace request is used to change the parameters of an existing order.
Cancel/Replace will be used to change quantity and price attribute of an open order
Do not use this message to cancel the remaining quantity of an outstanding order, use the Cancel Request message for this purpose.
Stipulates that a newly entered order is to cancel a prior order entered, but yet to be executed.
Method: cancelReplaceOrder
Params:
Name | Type | Description |
---|---|---|
clientOrderId | String | Required parameter. Replaced order |
requestClientId | String | clientOrderId for new order Required parameter. Uniqueness must be guaranteed within a single trading day, including all active orders. |
quantity | Number | New order quantity |
price | Number | New order price. |
strictValidate | Boolean | Price and quantity will be checked that they increment within tick size and quantity step. See symbol tickSize and quantityIncrement |
Example:
{
"method": "cancelReplaceOrder",
"params": {
"clientOrderId": "9cbe79cb6f864b71a811402a48d4b5b1",
"requestClientId": "9cbe79cb6f864b71a811402a48d4b5b2",
"quantity": "0.002",
"price": "0.083837"
},
"id": 123
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"id": "4346371528",
"clientOrderId": "9cbe79cb6f864b71a811402a48d4b5b2",
"symbol": "ETHBTC",
"side": "sell",
"status": "new",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.002",
"price": "0.083837",
"cumQuantity": "0.000",
"createdAt": "2017-10-20T12:47:07.942Z",
"updatedAt": "2017-10-20T12:50:34.488Z",
"reportType": "replaced",
"originalRequestClientOrderId": "9cbe79cb6f864b71a811402a48d4b5b1"
},
"id": 123
}
Method: getOrders
Example:
{
"method": "getOrders",
"params": {},
"id": 123
}
Example response:
{
"jsonrpc": "2.0",
"result": [
{
"id": "4346371528",
"clientOrderId": "9cbe79cb6f864b71a811402a48d4b5b2",
"symbol": "ETHBTC",
"side": "sell",
"status": "new",
"type": "limit",
"timeInForce": "GTC",
"quantity": "0.002",
"price": "0.083837",
"cumQuantity": "0.000",
"createdAt": "2017-10-20T12:47:07.942Z",
"updatedAt": "2017-10-20T12:50:34.488Z",
"reportType": "replaced",
"originalRequestClientOrderId": "9cbe79cb6f864b71a811402a48d4b5b1"
}
],
"id": 123
}
Method: getTradingBalance
Example:
{
"method": "getTradingBalance",
"params": {},
"id": 123
}
Example response:
{
"jsonrpc": "2.0",
"result": [
{
"currency": "BCN",
"available": "100.000000000",
"reserved": "0"
},
{
"currency": "BTC",
"available": "0.013634021",
"reserved": "0"
},
{
"currency": "ETH",
"available": "0",
"reserved": "0.00200000"
}
],
"id": 123
}