MEET NEW VERSION OF HITBTC API!

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

Table of Contents

• Development guide
• Best practices
• REST API Reference
  • API Explorer
  • Examples
  • Market data
    • Currencies
    • Symbols
    • Tickers
    • Trades
    • Orderbook
    • Candles
  • Authentication
  • Trading
    • Get trading balance
    • Get active orders
    • Get active order
    • Create new order
    • Cancel order
    • Cancel all orders
    • Trading commission
  • Trading history
    • Orders history
    • Trades history
    • Trades by order
  • Account
    • Account balance
    • Deposit address
    • Withdraw crypto
    • Commit or Rollback Withdraw crypto
    • Transfer between trading and account
    • Transactions
• Socket API Reference
  • Market Data
    • Get Currencies
    • Get Symbols
    • Subscribe to ticker
    • Subscribe to orderbook
    • Subscribe to trades
    • Get trades
    • Subscribe to candles
  • Authentication
  • Trading
    • Subscribe to reports
    • Place New Order
    • Cancel Order
    • Cancel Replace Orders
    • Get active Orders
    • Get trading balance

DEVELOPMENT GUIDE

API URLs

Environment	REST	Streaming
PROD	https://api.hitbtc.com/api/2	wss://api.hitbtc.com/api/2/ws

DateTime Format

All timestamps are returned in ISO8601 format in UTC. Example: "2017-04-03T10:20:49.315Z"

Number Format

All finance data, i.e. price, quantity, fee etc., should be arbitrary precision numbers and string representation. Example: "10.2000058"

Pagination

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

BEST PRACTICES

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.

HTTP Persistent Connection

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.

Retrieving and updating account state

Use Streaming API for real time updates of your orders and trades and any transactions changes.

REST API Reference

HTTP Status codes

• 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

Error response

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

API Explorer

You can explore API using SwaggerUI (https://api.hitbtc.com/api/2/explore/)

API Sample code

• Python rest example example_rest.py

Market data

Currencies

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

Symbols

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

Tickers

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

Trades

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

Orderbook

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

Candles

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

Authentication

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 

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:

importrequestsr=requests.get('https://api.hitbtc.com/api/2/trading/balance', auth=('ff20f250a7b3a414781d1abe11cd8cee', 'fb453577d11294359058a9ae13c94713')) print(r.json())

Trading

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	sellbuy
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 Active orders

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 Active order by clientOrderId

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

Create New Order

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 timeInForceIOC 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	sellbuy
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:

importrequestsorderData= {'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"
}
}

Cancel orders

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

Cancel order by clientOrderId

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 trading commission

GET /api/2/trading/fee/{symbol}

Get personal trading commission rate.

Example response:

{
"takeLiquidityRate": "0.001",
"provideLiquidityRate": "-0.0001"
}

Trading history

Please note, that trading history may be updated with delay up to 30 seconds, with mean delay around 1 second.

Orders history

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

Trades history

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

Trades by order

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	sellbuy
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

Account information

Account balance

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

Deposit crypto address

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

Withdraw crypto

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

Withdraw crypto commit or rollback

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
}

Transfer money between trading and account

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 transactions history

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

Socket API Reference

Use JSON-RPC 2.0 over WebSocket connection as transport.

Request object

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.

Notification

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.

Response object

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

Market Data

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
}

Get Currencies

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
}

Get Symbols

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
}

Subscribe to Ticker

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

Subscribe to Orderbook

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
}
}

Subscribe to Trades

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

Get Trades

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
}

Subscribe to Candles

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

Authentication Session

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

Socket Trading

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.

Subscribe to reports

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

Place New Order

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	sellbuy
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

Cancel Order

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
}

Cancel Replace Orders

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
}

Get active Orders

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
}

Get trading balance

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
}