HitBTC API Guide

HitBTC API Guide
Table of contents
 SUMMARY
— Currency symbols
 RESTFUL API
— Market data
— Trading
— Payment
 SOCKET.IO API
— Market Data
 STREAMING API
— Market data
— Trading
— Sample code
 Exapmles
— PHP Library
— NodeJs
Summary
Este documento proporciona la referencia completa para la API de HitBTC.
HitBTC API tiene varias interfaces para implementarlas en un software personalizado:
 RESTful API that allows:

o access to the market data: get ticker, order book, trades, etc. See Market
data RESTful API
o performing trading operations: get trading balance, place or cancel
orders, get history, etc. See Trading RESTful API
o managing funds: get balance of the main account, transfer funds between
main and trading accounts, create an outgoing transactions, etc. See
Payment RESTful API
 socket.io protocol for receiving the market data. socket.io protocol supports
WebSocket and xhr-polling transport. See socket.io Market Data
 Streaming API based on WebSocket protocol to get an access to:
o market data. See Market data streaming end-point
o trading operations. See Trading streaming end-point
Trading and payment operations require user's authentication: each request or message
should have a signature. You should get your API key and Secret key on the Settings
page. See details in RESTful API authentication and WebSocket API authentication.
Currency symbols
Tenga en cuenta que USD significa USDT crypto currency tether.to.

Los siguientes símbolos de moneda se negocian en el intercambio HitBTC..
Symbol Lot size Price step
BTCUSD 0.01 BTC 0.01
BTCEUR 0.01 BTC 0.01
LTCBTC 0.1 LTC 0.00001
LTCUSD 0.1 LTC 0.001
LTCEUR 0.1 LTC 0.001
DSHBTC 1 DSH 0.00000001
ETHBTC 0.001 ETH 0.000001
ETHEUR 0.001 ETH 0.0001
NXTBTC 1 NXT 0.00000001
BCNBTC 100 BCN 0.0000000001
XDNBTC 100 XDN 0.0000000001
DOGEBTC 1000 DOGE 0.000000001
XMRBTC 0.01 XMR 0.000001
QCNBTC 0.01 QCN 0.000001
FCNBTC 0.01 FCN 0.000001
LSKBTC 1 LSK 0.0000001
LSKEUR 1 LSK 0.0001
STEEMBTC 0.001 STEEM 0.00001
STEEMEUR 0.001 STEEM 0.0001
SBDBTC 0.001 SBD 0.00001
DASHBTC 0.001 DASH 0.000001
XEMBTC 1 XEM 0.00000001
EMCBTC 0.1 EMC 0.00000001
SCBTC 100 SC 0.000000001
ARDRBTC 1 ARDR 0.000000001
ZECBTC 0.001 ZEC 0.000001
WAVESBTC 0.01 WAVES 0.0000001
The actual list of symbols can be obtained by /api/1/public/symbols method.
Size representation:
 Size values in streaming messages are represented in lots.

 Size values in RESTful market data are represented in money (e.g. in coins or in
USD).
 Size values in RESTful trade are represented in lots (e.g. 1 means 0.01 BTC for
BTCUSD)
RESTful API
RESTful API provides the most functional access to HitBTC facilities. RESTful API
allows:
 access to the market data: get ticker, order book, trades, etc. See Market data
RESTful API
 performing trading operations: get trading balance, place or cancel orders, get
history, etc. See Trading RESTful API
 managing funds: get balance of the main account, transfer funds between main
and trading accounts, create an outgoing transactions, etc. See Payment RESTful
API
Endpoint URL: http://api.hitbtc.com.
HitBTC provides a demo trading option. You can enable demo mode and acquire
demo API keys on the Settings page.
Demo endpoint address: http://demo-api.hitbtc.com
Trading and payment operations require authentication. See also error codes and reports
representing order status changes.
Market data RESTful API

RESTful API provides access to the market data with following methods:
 get the timestamp- /api/1/public/time

 get the list of symbols - /api/1/public/symbols
 get the ticker for specified symbol - /api/1/public/:symbol/ticker
 get all tickers - /api/1/public/ticker
 get the order book for specified symbol - /api/1/public/:symbol/orderbook
 get individual trades data for specified symbol - /api/1/public/:symbol/trades
 get recent trades for specified symbol - /api/1/public/:symbol/trades/recent
/api/1/public/time
Summary: returns the server time in UNIX timestamp format
Request: GET /api/1/public/time
Example: /api/1/public/time
Example response:
{
"timestamp": 1393492619000
}
/api/1/public/symbols
Summary: Simbols returns the actual list of currency symbols traded on HitBTC
exchange with their characteristics:
Field Description
Field Description
symbol Symbol name
step Price step parameter
lot Lot size parameter
currency Value of this symbol
commodity Second value of this symbol
takeLiquidityRate Liquidity taker fee
provideLiquidityRate Liquidity provider rebate
Request: GET /api/1/public/symbols
Example: /api/1/public/symbols
Example response:
{
"symbols": [
{
"symbol": "BTCUSD",
"step": "0.01",
"lot": "0.01",
"currency": "USD",
"commodity": "BTC",
"takeLiquidityRate": "0.002",
"provideLiquidityRate": "0.002"
},
{
"symbol": "BTCEUR",
"step": "0.01",
"lot": "0.01",
"currency": "EUR",
"commodity": "BTC",
"takeLiquidityRate": "0.002",
"provideLiquidityRate": "0.002"
},
...
]
}
/api/1/public/:symbol/ticker
Summary: returns the actual data on exchange rates of the specified cryptocurrency.
Sample usage at HitBTC site: see https://hitbtc.com/market-overview for each line.
Request: GET /api/1/public/:symbol/ticker where :symbol is a currency symbol

traded on HitBTC exchange (see Currency symbols)
Example: /api/1/public/BTCUSD/ticker
Example response:
{
"last": "550.73",
"bid": "549.56",
"ask": "554.12",
"high": "600.1",
"low": "400.7",
"volume": "567.9",
"open": "449.73",
"volume_quote": "289002.81",
"timestamp": 1393492619000
The following fields are used in the ticker object:
Field Description
last Last price
bid Highest buy order
ask Lowest sell order
high Highest trade price per last 24h + last incomplete minute
low Lowest trade price per last 24h + last incomplete minute
volume Volume per last 24h + last incomplete minute
open Price in which instrument open
volume_quote Volume in second currency per last 24h + last incomplete minute
timestamp Server time in UNIX timestamp format
/api/1/public/ticker
Summary: returns the actual data on exchange rates for all traded cryptocurrencies - all
tickers.
Example: /api/1/public/ticker
Example response:
{
"BCNBTC": {
"ask": "0.000000039",
"bid": "0.000000036",
"last": "0.000000037",
"low": "0.000000035",
"high": "0.000000048",
"volume": "580790000",
"volume_quote": "26.000000000",
"timestamp": 1409907025743
},
"BTCEUR": {
"ask": "378.23",
"bid": "376.28",
"last": "376.29",
"low": "362.48",
"high": "382.13",
"volume": "961.71",
"volume_quote": "361328.13",
"timestamp": 1409907025743
},
"BTCUSD": {
"ask": "489.26",
"bid": "488.08",
"last": "489.31",
"low": "478.01",
"high": "496.23",
"volume": "404.20",
"volume_quote": "197735.83",
"timestamp": 1409907025743
}
....
}
/api/1/public/:symbol/orderbook
Summary: returns a list of open orders for specified currency symbol: their prices and
sizes.
Sample usage at HitBTC site: see https://hitbtc.com/exchange, Order book tab.
Request: GET /api/1/public/:symbol/orderbook where :symbol is a currency

symbol traded on HitBTC exchange (see Currency symbols)
Parameters:
Parameter Required Type Description

format_price string or Format of prices returned: as a string
No
number (default) or as a number
format_amount string or Format of amount returned: as a string
No
number (default) or as a number
format_amount_unit currency or Units of amount returned: in currency
No
lot units (default) or in lots
Alias: /api/1/request/:symbol/orderbook.json ->

/api/1/public/:symbol/orderbook?format_price=number&format_amount=numb
er
Example: /api/1/public/BTCUSD/orderbook
Example response:
{
"asks": [
[ "405.71", "0.09" ],
[ "406.65", "0.06" ],
[ "409.51", "0.15" ],
[ "413.93", "51.6" ],
[ "414.59", "47.1" ]
],
"bids": [
[ "398.3", "0.15" ],
[ "396.99", "0.13" ],
[ "395", "0.5" ],
[ "391.93", "42.4" ],
[ "383.67", "145.4" ]
]
}
Example:
/api/1/public/BTCUSD/orderbook?format_price=number&format_amount=numbe
r
Example response:
{
"asks": [
[ 405.71, 0.09 ],
[ 406.65, 0.06 ],
[ 409.51, 0.15 ],
[ 413.93, 51.6 ],
[ 414.59, 47.1 ]
],
"bids": [
[ 398.3, 0.15 ],
[ 396.99, 0.13 ],
[ 395, 0.5 ],
[ 391.93, 42.4 ],
[ 383.67, 145.4 ]
]
}
/api/1/public/:symbol/trades
Summary: returns data on trades for specified currency symbol in specified ID or

timestamp interval.
Sample usage at HitBTC site: see https://hitbtc.com/reports/all-trades.
Request: GET /api/1/public/:symbol/trades where :symbol is a currency symbol

traded on HitBTC exchange (see Currency symbols)
Parameters:
Parameter Reqired Type Description

Returns trades with trade_id >
from
specified trade_id (if by=trade_id)
Yes integer
or returns trades with timestamp >=
specified timestamp (if by=ts)
Returns trades with trade_id <
till
specified trade_id (if by=trade_id)
No integer
or returns trades with timestamp <
specified timestamp (if by=ts)
by
Selects if filtering and sorting is
Yes trade_id or ts
performed by trade_id or by timestamp
Parameter Reqired Type Description
sort
Trades are sorted ascending (default)
No asc or desc
or descending
start_index Yes integer Start index for the query, zero-based
max_results
Maximum quantity of returned items,
Yes integer
at most 1000
format_item array or Format of items returned: as an array
No object (default) or as a list of objects
format_price string or Format of prices returned: as a string
No number (default) or as a number
format_amount string or Format of amount returned: as a string
No number (default) or as a number
format_amount_unit currency or Units of amount returned: in currency
No lot units (default) or in lots
format_tid string or Format of trade ID returned: as a string
No number or as a number (default)
millisecond Format of trade timestamp returned: in
format_timestamp No or second milliseconds (default) or in seconds
Selects if the line wrappnig is used in
format_wrap No true or false
item returned. Default value - true
side No true or false Selects if the side of a trade is returned
Alias:
/api/1/request/:symbol/trades.json?since=<trade_id> ->
/api/1/public/:symbol/trades?from=<trade_id>&by=trade_id&start_index=0
&format_numbers=number&format_tradeid=string&format_objects=object&for
mat_timestamp=second
Example:
/api/1/public/BTCUSD/trades?from=0&by=trade_id&sort=desc&start_index=0
&max_results=100
Example response:
{
"trades": [
[ 3814483, "575.64", "0.02", 1393492619000 ],
[ 3814482, "574.3", "0.12", 1393492619000 ],
[ 3814481, "573.67", "3.8", 1393492619000 ],
[ 3814479, "571", "0.01", 1393492619000 ],
...
]
}
Example:
/api/1/public/BTCUSD/trades?from=0&by=trade_id&sort=desc&start_index=0
&max_results=100&format_item=object&format_price=number&format_amount=
number&format_tid=string&format_timestamp=second&format_wrap=false
Example response:
[
{"date": 1393492619, "price": 575.64, "amount": 0.02, "tid":
"3814483"},
"3814482"},
"3814481"},
{"date": 1393492619, "price": 571, "amount": 0.01, "tid":
"3814479"},
...
]
/api/1/public/:symbol/trades/recent
Summary: returns recent trades for the specified currency symbol.
Sample usage at HitBTC site: see https://hitbtc.com/reports/all-trades, Market trades

tab. Select the currency pair at top of the tab.
Request: /api/1/public/:symbol/trades/recent where :symbol is a currency

symbol traded on HitBTC exchange (see Currency symbols)
Parameters:

max_results
Maximum quantity of returned results, at most
Yes integer
1000
format_item array or Format of items returned: as an array (default) or
No
object as a list of objects
side true or
No Selects if the side of a trade is returned
false
Example:
/api/1/public/LTCEUR/trades/recent?max_results=100&format_item=object
Example response:
{"trades":[
{"date":1411045690003,"price":"442.12","amount":"0.09","tid":1413901,"
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"},
side":"buy"}
]
Trading RESTful API

RESTful API allows to perform trading operations with the following methods:
 get the trading balance - /api/1/trading/balance

 get all active orders - /api/1/trading/active
 place a new order - /api/1/trading/new_order
 cancel an order - /api/1/trading/cancel_order
 cancel all orders - /api/1/trading/cancel_orders
 get user's recent orders - /api/1/trading/recent
 get user's orders by clientOrderId - /api/1/trading/order
 get trades by clientOrderId - /api/1/trading/trades/by/order
 get user's trading history - /api/1/trading/trades
Trading operations require authentication.
Error codes and reports representing order status changes are described below.
Authentication
RESTful Trading API requires HMAC-SHA512 signatures for each request.
To use this API endpoint you should get your API key and Secret key from the Settings
page.
Each request should include the following parameters:

Unique monotonous number that
nonce
query string parameter, less should be generated on the client.
Yes
than (2^53-1) Hint: use millisecond or
microsecond timestamp
apikey Yes query string parameter API key from Settings page
lower-case hex
representation of hmac- This parameter should be added as
signature Yes
sha512 of concatenated uri a HTTP header X-Signature
and postData
Signature generation pseudo-code:
uri = path + '?' + query (example:

/api/1/trading/orders/active?nonce=1395049771755&apikey=f6ab189hd7a200
7e01d95667de3c493d&symbols=BTCUSD)
message = uri + postData
signature = lower_case(hex(hmac_sha512(message, secret_key)))
Javascript code (example):
var crypto = require('crypto');
...
var signature = crypto.createHmac('sha512',

secretKey).update(message).digest('hex');
Useful examples provided by the community:
 C# example code: https://gist.github.com/hitbtc-com/9808530

 PHP example code: https://gist.github.com/hitbtc-com/10885873
 PHP SDK: https://github.com/hitbtc-com/hitbtc-php-sdk
 JAVA example code: https://gist.github.com/hitbtc-
com/2765a1431a2384975c01
 Python example code: https://gist.github.com/hitbtc-
com/e265a49c38a86c610294
Error codes
Trading RESTful API can return the following errors:
HTTP
Text Description
code
API key doesn't exist or API key is currently used on
403 Invalid API key
another endpoint (max last 15 min)
Nonce has been
403 Nonce is not monotonous
used
Nonce is not
403 Too big number or not a number
valid
Wrong
403 Specified signature is not correct
signature
500 Internal error Internal error. Try again later
Execution reports
The API uses ExecutionReport as an object that represents change of order status.
The following fields are used in ExecutionReport object:
Field Required Type Description

orderId Yes string Order ID on the Exchange
clientOrderId sent in
clientOrderId Yes string NewOrder message (see
/api/1/trading/new_order)
new
canceled
rejected
execReportType Yes Execution report type
expired
trade
status
new
partiallyFilled
filled
orderStatus Yes Order status
canceled
rejected
expired
unknownSymbol
exchangeClosed
Yes - for orderExceedsLimit Reason of rejection. Relevant
unknownOrder
orderRejectReason orders in only for orders in rejected
rejected duplicateOrder
state unsupportedOrder state
unknownAccount
other
Currency symbol traded on
symbol Yes string, e.g. BTCUSD HitBTC exchange (see
Currency symbols)
side Yes buy or sell Side of a trade
timestamp
UTC timestamp in
No integer
milliseconds
price No decimal Price of an order
quantity Yes integer Order quantity in lots
limit, stopLimit,
type Yes Type of an order.
stopMarket, market
GTC - Good-Til-
Canceled
IOC - Immediate-Or-
timeInForce Yes Time in force
Cancel
FOK - Fill-Or-Kill
DAY - day orders<
tradeId
Yes - for
integer Trade ID on the exchange
trades
lastQuantity Yes - for integer Last quantity
trades
lastPrice
Yes - for
decimal Last price
trades
leavesQuantity No integer Leaves quantity
cumQuantity No integer Cumulative quantity
Average price. Equals 0 if
averagePrice No decimal
cumQuantity=0
Example response:
{ "ExecutionReport": {
"orderId": "5852103",
"clientOrderId": "11111112",
"execReportType": "new",
"orderStatus": "new",
"symbol": "BTCUSD",
"side": "buy",
"timestamp": 1395236779235,
"price": 0.1,
"quantity": 100,
"type": "limit",
"timeInForce": "GTC",
"lastQuantity": 0,
"lastPrice": 0,
"leavesQuantity": 100,
"cumQuantity": 0,
"averagePrice": 0
} }
/api/1/trading/balance
Summary: returns trading balance.
Sample usage at HitBTC site: see https://hitbtc.com/terminal, the upper panel, Trading
line. The black number displays total trade balance of the currency (cash parameter),
the gray number is amount reserved against unexecuted orders and unfinished
transactions (reserved parameter).
Request: GET /api/1/trading/balance
Parameters: no parameters
Example response:
{"balance": [
{"currency_code": "BTC","cash": 0.045457701,"reserved": 0.01},
{"currency_code": "EUR","cash": 0.0445544,"reserved": 0},
{"currency_code": "LTC","cash": 0.7,"reserved": 0.1},
{"currency_code": "USD","cash": 2.9415029,"reserved": 1.001}
]}
/api/1/trading/orders/active
Summary: returns all orders in status new or partiallyFilled.
Sample usage at HitBTC site: see https://hitbtc.com/terminal, My orders tab, Active

group.
Request: GET /api/1/trading/orders/active
Parameters:

symbols
Comma-separated list of symbols. Default - all
No string
symbols
clientOrderId No string Unique order ID
Example response:
{"orders": [
{
"orderId": "51521638",
"lastTimestamp": 1394798401494,
"orderPrice": 1000,
"orderQuantity": 1,
"avgPrice": 0,
"quantityLeaves": 1,
"type": "limit",
"cumQuantity": 0,
"clientOrderId": "7fb8756ec8045847c3b840e84d43bd83",
"symbol": "LTCBTC",
"side": "sell",
"execQuantity": 0
}
]}
/api/1/trading/new_order
Summary: place a new order. Returns a JSON object ExecutionReport that respresent
a status of the order.
Sample usage at HitBTC site: see https://hitbtc.com/terminal, Sell Order and Buy
Order panels.
Request: POST /api/1/trading/new_order
Parameters:

clientOrderId
Unique order ID generated by
Yes string
client. From 8 to 32 characters
symbol
Yes string
HitBTC exchange (see
Currency symbols), e.g.
BTCUSD
price
Yes - for limit
decimal Order price
orders
quantity No integer Order quantity in lots
limit, stopLimit,
type No stopMarket, Order type
market
GTC - Good-Til-
Canceled
IOC - Immediate- Time in force. Default value -
timeInForce No
Or-Cancel GTC
FOK - Fill-Or-Kill
DAY - day
Yes - for
stopPrice stopLimit, string Stop price
stopMarket
Example:
post url:
/api/1/trading/new_order?nonce=1395049771755&apikey=f6ab189hd7a2007e01
d95667de3c493d
post data:
clientOrderId=11111112&symbol=BTCUSD&side=buy&price=0.1&quantity=100&t
ype=limit&timeInForce=GTC
Example response:
{ "ExecutionReport":
{ "orderId": "58521038",
"symbol": "BTCUSD",
"side": "buy",
"timestamp": 1395236779235,
"price": 0.1,
"quantity": 100,
"type": "limit",
"lastQuantity": 0,
"lastPrice": 0,
"cumQuantity": 0,
"averagePrice": 0 } }
/api/1/trading/cancel_order
Summary: cancels an order. Returns ExecutionReport JSON object or CancelReject

JSON object.
Sample usage at HitBTC site: see https://hitbtc.com/terminal, My Orders tab. Click
Cancel button in required order line.
Request: POST /api/1/trading/cancel_order
Parameters:

clientOrderId
Order ID, the same as in cancelling
Yes string
order, from 8 to 32 characters
cancelRequestClientOrderId
Unqiue ID generated by client,
No string
from 8 to 32 characters
symbol
Currency symbol, the same as in
No string
cancelling order
side buy or Side of a trade, the same as in
No sell cancelling order
Example:
post url:
/api/1/trading/cancel_order?nonce=1395049771755&apikey=f6ab189hd7a2007
e01d95667de3c493d
post data:
clientOrderId=11111112&cancelRequestClientOrderId=38257825798349578945
&symbol=BTCUSD&side=buy
Example response:
{ "ExecutionReport":
{ "orderId": "58521038",
"execReportType": "canceled",
"orderStatus": "canceled",
"symbol": "BTCUSD",
"side": "buy",
"timestamp": 1395236779346,
"price": 0.1,
"quantity": 100,
"type": "limit",
"lastQuantity": 0,
"lastPrice": 0,
"cumQuantity": 0,
"averagePrice": 0 } }
CancelReject example:
{ "CancelReject": {
"cancelRequestClientOrderId": "011111112",
"rejectReasonCode": "orderNotFound"
} }
/api/1/trading/cancel_orders
Summary: cancels all orders. Returns ExecutionReport array of JSON object.
Request: POST /api/1/trading/cancel_orders
Parameters:

symbols
Comma-separated list of symbols. Default - all
No string
symbols
side buy or
No Side of a trade
sell
Example:
post url:
/api/1/trading/cancel_orders?nonce=1395049771755&apikey=f6ab189hd7a200
7e01d95667de3c493d
post data: symbols=BTCUSD
Example response:
{
"ExecutionReport": [
{
"orderId": "411459298",
"clientOrderId": "7bd65b9cc64e436a89edef57b841f691",
"symbol": "BTCUSD",
"side": "sell",
"price": "280.00",
"quantity": 1,
"type": "limit",
"lastQuantity": 0,
"lastPrice": "",
"cumQuantity": 0,
"averagePrice": "0",
"created": 1443530022688,
"timestamp": 1443530050131
},
{
"orderId": "411459299",
"clientOrderId": "a6b41105b54c4304bf7bd8bca29fb060",
"symbol": "BTCUSD",
"side": "sell",
"price": "290.00",
"quantity": 15,
"type": "limit",
"lastQuantity": 0,
"lastPrice": "",
"cumQuantity": 0,
"averagePrice": "0",
"created": 1443530030502,
"timestamp": 1443530050131
}
]
}
/api/1/trading/orders/recent
Summary: returns an array of user's recent orders (order objects) for last 24 hours,
sorted by order update time.
Sample usage at HitBTC site: see https://hitbtc.com/terminal, My orders tab.
Request: GET /api/1/trading/orders/recent
Parameters:

start_index No integer Zero-based index, 0 by default
max_results
Maximum quantity of returned items, at
Yes integer
most 1000
sort
Orders are sorted ascending (default) or
No asc or desc
descending
symbols No string Comma-separated list of currency symbols
new
partiallyFilled
filled
statuses No Comma-separated list of order statuses
canceled
expired
rejected
The following fields are used in order object:

orderId No integer Order ID on the exchange
new
partiallyFilled
filled
orderStatus No Order status
canceled
expired
rejected
lastTimestamp
UTC timestamp of the last
Yes integer
change, in milliseconds
orderPrice
Yes - for limit
decimal Order price
orders
orderQuantity Yes integer Order quantity, in lots
avgPrice Yes decimal Average price
quantityLeaves Yes integer Remaining quantity, in lots
type No limit or market Type of an order
GTC - Good-Til-
Canceled
IOC - Immediate-Or-
timeInForce No Time in force
Cancel
FOK - Fill-Or-Kill
DAY - day
clientOrderId No string Unique client-generated ID
symbol No string Currency symbol
side No buy or sell Side of a trade
execQuantity No integer Last executed quantity, in lots
Example response:
{"orders": [
{
"orderId": "1",
"orderPrice": 1,
"orderQuantity": 1,
"avgPrice": 0,
"type": "limit",
"clientOrderId": "111111111111111111111111",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 0
},
{
"orderId": "2",
"orderPrice": 1,
"orderQuantity": 1,
"avgPrice": 0,
"type": "limit",
"clientOrderId": "111111111111111111111112",
"symbol": "BTCUSD",
"side": "sell",
"execQuantity": 0
},
{
"orderId": "3",
"orderPrice": 1,
"orderQuantity": 1,
"avgPrice": 0,
"type": "limit",
"clientOrderId": "111111111111111111111113",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 0
}
]}
/api/1/trading/order
Summary: returns an array of user's orders (order objects).
Request: GET /api/1/trading/order
Parameters:

client_order_id No string Unique client-generated ID
The following fields are used in order object:

orderId No integer Order ID on the exchange
new
partiallyFilled
filled
orderStatus No Order status
canceled
expired
rejected
lastTimestamp
UTC timestamp of the last
Yes integer
change, in milliseconds
orderPrice
Yes - for limit
decimal Order price
orders
orderQuantity Yes integer Order quantity, in lots
avgPrice Yes decimal Average price
quantityLeaves Yes integer Remaining quantity, in lots
type No limit or market Type of an order
GTC - Good-Til-
Canceled
IOC - Immediate-Or-
timeInForce No Time in force
Cancel
FOK - Fill-Or-Kill
DAY - day
clientOrderId No string Unique client-generated ID
side No buy or sell Side of a trade
execQuantity No integer Last executed quantity, in lots
Example response:
{
"orders": [
{
"orderId": 425817975,
"orderStatus": "filled",
"orderPrice": "0.0000000729",
"orderQuantity": 10,
"avgPrice": "0.0000000810",
"type": "market",
"timeInForce": "FOK",
"cumQuantity": 10,
"clientOrderId": "afe8b9901b0e4914991291a49175a380",
"symbol": "BCNBTC",
"side": "sell",
"execQuantity": 10
}
]
}
/api/1/trading/trades/by/order
Summary: returns all trades of specified order (trade objects).
Request: GET /api/1/trading/trades/by/order
Parameters:

clientOrderId Yes string Unique order ID generated by client
The following fields are used in trade object:

tradeId Yes integer Trade ID on the exchange
execPrice Yes decimal Trade price
timestamp Yes integer Timestamp, in milliseconds
originalOrderId No integer Order ID on the exchange
fee
Fee for the trade, negative value means
No decimal
rebate
clientOrderId No string Client order id from the request
side buy or
No Side of a trade
sell
execQuantity No integer Trade size, in lots
Example response:
{"trades": [
{
"tradeId": 39,
"execPrice": 150,
"timestamp": 1395231854030,
"originalOrderId": "114",
"fee": 0.03,
"clientOrderId": "FTO18jd4ou41--25",
"symbol": "BTCUSD",
"side": "sell",
"execQuantity": 10
},
{
"tradeId": 38,
"execPrice": 140.1,
"timestamp": 1395231853882,
"fee": 0.028,
"clientOrderId": "FTO18jd4ou3n--15",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 10
},
{
"tradeId": 2,
"execPrice": 150,
"timestamp": 1394789991659,
"fee": 0.03,
"clientOrderId": "FTO18ivvcbvt--25",
"symbol": "BTCUSD",
"side": "sell",
"execQuantity": 10
},
{
"tradeId": 1,
"execPrice": 140,
"timestamp": 1394789991527,
"fee": 0.028,
"clientOrderId": "FTO18ivvcbvj--15",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 10
}
]}
/api/1/trading/trades
Summary: returns the trading history - an array of user's trades (trade objects).
Sample usage at HitBTC site: https://hitbtc.com/reports/trades. Trades for preceding 24

hours see https://hitbtc.com/terminal, My trades tab.
Request: GET /api/1/trading/trades
Parameters:
trade_id Selects if filtering and sorting is performed by
by Yes or ts trade_id or by timestamp
start_index Yes integer Zero-based index. Default value is 0
max_results
Maximum quantity of returned results, at most
Yes integer
1000
symbols No string Comma-separated list of currency symbols
sort asc or Trades are sorted ascending (default) or
No desc descending
Returns trades with trade_id > specified
from No integer trade_id (if by=trade_id) or returns trades with
timestamp >= specified timestamp(ifby=ts`)
Returns trades with trade_id < specified
till No integer trade_id (if by=trade_id) or returns trades with
timestamp < specified timestamp (if by=ts)
The following fields are used in trade object:

tradeId Yes integer Trade ID on the exchange
execPrice Yes decimal Trade price
timestamp Yes integer Timestamp, in milliseconds
originalOrderId No integer Order ID on the exchange
fee No decimal Fee for the trade, negative value means rebate
clientOrderId
Unique order ID generated by client. From 8
No string
to 32 characters
side buy or
No Side of a trade
sell
execQuantity No integer Trade size, in lots
Example response:
{"trades": [
{
"tradeId": 39,
"execPrice": 150,
"timestamp": 1395231854030,
"fee": 0.03,
"clientOrderId": "FTO18jd4ou41--25",
"symbol": "BTCUSD",
"side": "sell",
"execQuantity": 10
},
{
"tradeId": 38,
"execPrice": 140.1,
"timestamp": 1395231853882,
"fee": 0.028,
"clientOrderId": "FTO18jd4ou3n--15",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 10
},
{
"tradeId": 2,
"execPrice": 150,
"timestamp": 1394789991659,
"fee": 0.03,
"clientOrderId": "FTO18ivvcbvt--25",
"symbol": "BTCUSD",
"side": "sell",
"execQuantity": 10
},
{
"tradeId": 1,
"execPrice": 140,
"timestamp": 1394789991527,
"fee": 0.028,
"clientOrderId": "FTO18ivvcbvj--15",
"symbol": "BTCUSD",
"side": "buy",
"execQuantity": 10
}
]}
Payment RESTful API

RESTful API allows to manage funds with the following methods:
 get multi-currency balance of the main account - /api/1/payment/balance

 transfer funds between main and trading accounts -
/api/1/payment/transfer_to_trading, /api/1/payment/transfer_to_main
 get the last created incoming cryptocurrency address or create a new one -
/api/1/payment/address/ (GET), /api/1/payment/address/ (POST),
 create an outgoing crypotocurrency transaction - /api/1/payment/payout
 get a list of payment transactions - /api/1/payment/transactions
 get a payment transaction - /api/1/payment/transactions/:id
Payment operations require authentication
/api/1/payment/balance
Summary: returns multi-currency balance of the main account.
Sample usage at HitBTC site: see https://hitbtc.com/account.
Request: GET /api/1/payment/balance
Example response:
{
"balance": [
{
"currency_code": "USD",
"balance": 13.12
},
{
"currency_code": "EUR",
"balance": 0
},
{
"currency_code": "LTC",
"balance": 1.07
},
{"currency_code": "BTC",
"balance": 11.9
}
]}
/api/1/payment/transfer_to_trading and /api/1/payment/transfer_to_main
Request: POST /api/1/payment/transfer_to_trading,

/api/1/payment/transfer_to_main
Summary: transfers funds between main and trading accounts; returns a transaction ID
or an error.
Sample usage at HitBTC site: see https://hitbtc.com/account. Click the appropriate

arrow in the currency line then specify required amount and click Transfer button.
Parameters:

amount Yes decimal Funds amount to transfer
currency_code Yes string Currency symbol, e.g. BTC
Example responses:
{"message": "Balance not enough", "statusCode": 409, "body": "Balance

not enough"}
{"transaction": "52976-103925-18443984"}
/api/1/payment/address/ (GET)
Summary: returns the last created incoming cryptocurrency address that can be used to
deposit cryptocurrency to your account.
Sample usage at HitBTC site: see https://hitbtc.com/account. In the required currency

line click Fund icon then click copy address link.
Request: GET /api/1/payment/address/:currency

Example: GET /api/1/payment/address/BTC
Example response:
{"address":"1HDtDgG9HYpp1YJ6kFYSB6NgaG2haKnxUH"}
/api/1/payment/address/ (POST)
Summary: creates an address that can be used to deposit cryptocurrency to your

account; returns a new cryptocurrency address.

line click Fund icon then click create new address link.
Request: POST /api/1/payment/address/:currency
Example: POST /api/1/payment/address/BTC
Example response:
{"address":"1HDtDgG9HYpp1YJ6kFYSB6NgaG2haKnxUH"}
/api/1/payment/payout
Summary: withdraws money and creates an outgoing crypotocurrency transaction;

returns a transaction ID on the exchange or an error.

line click Fund icon then click copy address link.
Request: POST /api/1/payment/payout
Parameters:

amount Yes decimal Funds amount to withdraw
currency_code Yes string Currency symbol, e.g. BTC
address Yes string BTC/LTC address to withdraw to
extra_id No string payment id for cryptonote
use recommended network fee instead of flat, e.g.
recommended_fee No boolean
0 or 1
Example:
amount=0.001&currency_code=BTC&address=1LuWvENyuPNHsHWjDgU1QYKWUYN9xxy
7n5
Example response:
{"transaction": "51545-103004-18442681"}
/api/1/payment/transactions
Summary: returns a list of payment transactions and their statuses (array of

transactions).
Sample usage at HitBTC site: see https://hitbtc.com/account, History panel.
Request: GET /api/1/payment/transactions
Parameters:

offset No integer Start index for the query, default = 0
limit Yes integer Maximum results for the query
dir ask or Transactions are sorted ascending or descending
No
desc (default)
Example response:
{"transactions": [
{
"id": "49720-104765-18440728",
"type": "payin",
"status": "pending",
"created": 1397056648,
"finished": 1397056646,
"amount_from": 0.001,
"currency_code_from": "BTC",
"amount_to": 0.001,
"currency_code_to": "BTC",
"destination_data": null,
"commission_percent": 0,
"bitcoin_address": "1KnVXD1Wc1wZbTHiB1TDgMcnSRi2PnMHAV",
"bitcoin_return_address": "1QBuhFksjoWTQWJKWUPyQ37wsQohLAhJvK"
"external_data":
"0b2ac379986cd1872b6a4115ad7a6cf436bdac67080db728579b8282c129a549"
}
]}
/api/1/payment/transactions/:id
Summary: returns payment transaction and its status.
Sample usage at HitBTC site: see https://hitbtc.com/account, History panel.
Request: GET /api/1/payment/transactions/89229-171-97181
Parameters:
id Yes string Transaction Id
Example response:
{
"transaction": {
"id": "89229-171-97181",
"type": "payin",
"status": "finished",
"created": 1438768402,
"finished": 1438768943,
"amount_from": 1000,
"currency_code_from": "BCN",
"amount_to": 1000,
"currency_code_to": "BCN",
"destination_data":
"b744ab8c87d83b6469770926cb5388e3f389f067730af7f506d1f08cbef46d86",
"commission_percent": 0,
"bitcoin_address": null,
"bitcoin_return_address": null,
"external_data":
"3b598fd882902d8be14bd72d2b31f692f34700bf133e62c442d487911465b72e"
}
}
socket.io Market Data

The API provides socket.io version 1.0.x protocol for receiving market data. It supports:
 WebSocket and xhr-polling transport

 multiplexing a single connection with socket.io namespaces (see trades
namespace)
Useful links:
 official socket.io documentation - http://socket.io/

 chrome extension Simple WebSocket Client -
https://chrome.google.com/webstore/detail/simple-websocket-
client/pfdhoblngboilpfeibdedpjgfnlcodoo. See also the Sample code
API links:
 socket.io URL: http://api.hitbtc.com:8081

 socket.io demo URL: http://demo-api.hitbtc.com:8081
 live example (both demo and primary API):
http://jsfiddle.net/rn7zy75n/1/
trades namespace
Namespace: trades
URLs: /trades/:symbol e.g. /trades/BTCUSD
Event: trade
Event example:
{"price":478.33,"amount":0.15}
Streaming API
Streaming API is based on WebSocket protocol. All messages are in JSON format.
Streaming API provides an access to:
 market data. See Market data streaming end-point

 trading operations. See Trading streaming end-point
Market data streaming end-point

API links:
 URL: ws://api.hitbtc.com:80
 Demo URL: ws://demo-api.hitbtc.com:80
Once client connects to this URL the session is started.
The server broadcasts the following types of messages:
 MarketDataSnapshotFullRefresh message contains a full snapshot of the order

book.
 MarketDataIncrementalRefresh message contains incremental changes
Some recommendations to consider:
 The application could receive the first snapshot and maintain the order book by
applying incremental updates.
 It's recommended to invalidate a state of the application periodically using
snapshots.
 It's recommended to check sequence numbers and to drop updates with non-
monotonous sequence numbers.
MarketDataSnapshotFullRefresh message
Summary: contains a full snapshot of the order book.
Example message:
{"MarketDataSnapshotFullRefresh": {
"snapshotSeqNo": 899009,
"symbol": "BTCUSD",
"exchangeStatus": "working",
"ask": [
{
"price": 101.42,
"size": 7
},
{
"price": 101.85,
"size": 5
},
{
"price": 102.59,
"size": 1
},
{
"price": 114.53,
"size": 3
},
{
"price": 114.54,
"size": 6
},
{
"price": 114.55,
"size": 19
}
],
"bid": [
{
"price": 89.72,
"size": 79
},
{
"price": 89.71,
"size": 158
},
{
"price": 89.7,
"size": 166
},
{
"price": 89.69,
"size": 231
},
{
"price": 89.68,
"size": 169
},
{
"price": 89.67,
"size": 186
},
{
"price": 89.66,
"size": 178
}
]
}}
The following fields are used in MarketDataSnapshotFullRefresh object:

Field Description
seqNo
Monotone increasing number of the snapshot, each symbol has its
own sequence
timestamp UTC timestamp, in milliseconds
symbol Currency symbol traded on HitBTC exchange
exchangeStatus Exchange status: on - trading is open; off - trading is suspended
Sorted arrays of price levels in the order book; full snapshot (all price
ask, bid
levels) is provided
MarketDataIncrementalRefresh message
Summary: contains incremental changes of the order book and individual trades.
Example message:
{"MarketDataIncrementalRefresh": {
"seqNo": 546693,
"timestamp": 1381394357861,
"symbol": "BTCUSD",
"exchangeStatus": "on",
"ask": [],
"bid": [
{
"price": 100.98,
"size": 3
}
],
"trade": [
{
"price": 100.98,
"size": 5,
"timestamp": 1346691273926
}
]
}}
The following fields are used in MarketDataIncrementalRefresh object:
Field Description
seqNo
Monotone increasing number of the snapshot, each symbol has its
own sequence
timestamp UTC timestamp, in milliseconds
symbol Currency symbol traded on HitBTC exchange
exchangeStatus Exchange status: on - trading is open; off - trading is suspended
An array of changes in the order book where price is a price, size is
ask, bid, trade
new size. size=0 means that the price level has been removed
Trading streaming end-point

API links:
 URL: wss://api.hitbtc.com:8080
 Demo URL: wss://demo-api.hitbtc.com:8080
Trading endpoint requires sending login message after connection established. All client
messages should be signed and should contain valid and active API key (see API keys
and message signatures).
The following message types are supported:
| Type | | | --- | --- | --- | | Login | Client -> Server | | NewOrder | Client -> Server | |
OrderCancel | Client -> Server | | ExecutionReport | Server -> Client | | CancelReject |
Server -> Client |
API keys and message signatures
All client messages should be signed in the following manner:
{
"apikey": "e418f5b4a15608b78185540ef583b9fc",
"signature":
"FN6/9dnMfLh3wZj+cAFr82HcSvmwuniMQqUlRxSQ9WxRqFpYrjY2xlvDzLC5+qSZAHts8
R7KR7HbjiI3SzVxHg==",
"message":{
"nonce": 12,
"payload": {
"Login": {}
}
}
}
Fields:
Field Description
nonce
Unique monotonous number that should be generated on the client. Should
be monotonous within the same connection
signature
Signature - hash-based message authentication code: base64 hmac-sha512
(binary representation of the message)
Login
Example:
{
"signature":
"message":{
"nonce": 12,
"payload": {
"Login": {}
}
}
}
If client doesn't send valid logon message in 10 second the connection will be dropped.
NewOrder
Example:
{
"signature":
"message":{
"nonce": 12,
"payload": {
"NewOrder": {
"clientOrderId": "68f82819-723a-4b60-ad6b",
"symbol": "BTCUSD",
"side": "buy",
"quantity": 10,
"type": "limit",
"price": 788.12,
"timeInForce": "GTC"
}
}
}
}
Parameters:
Parameter Type Description

clientOrderId
Unique order ID generated by client. From 8 to
string
32 characters
symbol string Currency symbol traded on HitBTC exchange
side buy, sell Order side
quantity integer Quantity, in lots
type
Order type. Only limit orders are currently
limit or market
supported
price decimal Price, in currency units, consider price steps
GTC - Good-Til-
Canceled
timeInForce IOC - Immediate-Or- Time in force
Cancel
FOK - Fill-Or-Kill
OrderCancel
Example:
{
"signature":
"message":{
"nonce": 12,
"payload": {
"OrderCancel": {
"cancelRequestClientOrderId": "2c4d7127-6fbc-450c-
b851-c6c1e8954545",
"symbol": "BTCUSD",
"side": "buy"
}
}
}
}
Parameters:
Parameter Type Description

clientOrderId parameter sent in
clientOrderId string
NewOrder message
cancelRequestClientOrderId
Unqiue ID generated by client, from 8 to
string
32 characters
symbol
Currency symbol traded on HitBTC
string
exchange
side buy, sell Order side
type limit or Order type. Only limit orders are
market currently supported
ExecutionReport
Example:
{
"ExecutionReport":{
"orderId": "64283442",
"orderStatus": "new"
"symbol": "BTCUSD",
"side": "buy",
"timestamp": 1346691273926,
"price": 690.99,
"quantity": 0.1,
"type": "limit",
"timeInForce": "GTC"
}
}
The following fields are used in ExecutionReport object:

orderId Yes string Order ID on the Exchange
clientOrderId sent in
clientOrderId Yes string NewOrder message (see
/api/1/trading/new_order)
new
canceled
rejected
execReportType Yes Execution report type
expired
trade
status
new
partiallyFilled
filled
orderStatus Yes Order status
canceled
rejected
expired
unknownSymbol
exchangeClosed
Yes - for orderExceedsLimit Reason of rejection. Relevant
unknownOrder
orderRejectReason orders in only for orders in rejected
rejected duplicateOrder
state unsupportedOrder state
unknownAccount
other
symbol Yes string, e.g. BTCUSD HitBTC exchange (see
Currency symbols)
timestamp
UTC timestamp in
No integer
milliseconds
price No decimal Price of an order
quantity Yes integer Order quantity in lots
type limit
Type of an order. Only limit
Yes
orders are currently supported
GTC - Good-Til-
Canceled
IOC - Immediate-Or-
timeInForce Yes Time in force
Cancel
FOK - Fill-Or-Kill
DAY - day orders<
tradeId
Yes - for
integer Trade ID on the exchange
trades
lastQuantity
Yes - for
integer Last quantity
trades
lastPrice
Yes - for
decimal Last price
trades
leavesQuantity No integer Leaves quantity
cumQuantity No integer Cumulative quantity
Average price. Equals 0 if
averagePrice No decimal
cumQuantity=0
CancelReject
Example:
{"CancelReject": {
"cancelRequestClientOrderId": "2c4d7127-6fbc-450c-b851",
"rejectReasonCode": "orderNotFound",
"rejectReasonText": "Order not found",
"timestamp": 726892347829
}}
The following fields are used in CancelReject object:
Require
Field Type Description
d
cancelRequestClientOrder
cancelRequestClientOrder
Id Yes string Id parameter from
OrderCancel
clientOrderId parameter
clientOrderId Yes string
from OrderCancel
orderNotFoun
d
rejectReasonCode
unknownSymbo Code of the reason why the
Yes l order was cancelled
unknownUser
other
rejectReasonText
Optional text explaining reject
No string
reason
Sample code
Node.js snippet: message signature
var crypto = require('crypto');
...
var msg = {
'apikey': apikey,
'signature': '',
'message': {
'nonce': nonce,
'payload': {
'NewOrder': {
'clientOrderId': clientOrderId,
'symbol': symbol,
'side': side,
'quantity': quantity,
'type': type,
'price': price,
'timeInForce': timeInForce
}
}
}
};
msg.signature = crypto.createHmac('sha512',
secretkey).update(JSON.stringify(msg.message)).digest('base64');
return JSON.stringify(msg);

HitBTC API Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

HitBTC API Guide

Uploaded by

Copyright:

Available Formats

HitBTC API Guide

 RESTful API that allows:

Tenga en cuenta que USD significa USDT crypto currency tether.to.

The actual list of symbols can be obtained by /api/1/public/symbols method.

 Size values in streaming messages are represented in lots.

Endpoint URL: http://api.hitbtc.com.

Market data RESTful API

 get the timestamp- /api/1/public/time

Summary: returns the server time in UNIX timestamp format

Request: GET /api/1/public/time

Request: GET /api/1/public/symbols

Sample usage at HitBTC site: see https://hitbtc.com/market-overview for each line.

Request: GET /api/1/public/:symbol/ticker where :symbol is a currency symbol

The following fields are used in the ticker object:

Sample usage at HitBTC site: see https://hitbtc.com/exchange, Order book tab.

Request: GET /api/1/public/:symbol/orderbook where :symbol is a currency

Parameter Required Type Description

Alias: /api/1/request/:symbol/orderbook.json ->

Summary: returns data on trades for specified currency symbol in specified ID or

Sample usage at HitBTC site: see https://hitbtc.com/reports/all-trades.

Request: GET /api/1/public/:symbol/trades where :symbol is a currency symbol

Parameter Reqired Type Description

Summary: returns recent trades for the specified currency symbol.

Sample usage at HitBTC site: see https://hitbtc.com/reports/all-trades, Market trades

Request: /api/1/public/:symbol/trades/recent where :symbol is a currency

Parameter Required Type Description

Trading RESTful API

 get the trading balance - /api/1/trading/balance

Trading operations require authentication.

RESTful Trading API requires HMAC-SHA512 signatures for each request.

Each request should include the following parameters:

Parameter Required Type Description

Signature generation pseudo-code:

uri = path + '?' + query (example:

Javascript code (example):

var crypto = require('crypto');

var signature = crypto.createHmac('sha512',

Useful examples provided by the community:

 C# example code: https://gist.github.com/hitbtc-com/9808530

Trading RESTful API can return the following errors:

The following fields are used in ExecutionReport object:

Field Required Type Description

Summary: returns trading balance.

Request: GET /api/1/trading/balance

Sample usage at HitBTC site: see https://hitbtc.com/terminal, My orders tab, Active

Request: GET /api/1/trading/orders/active

Parameter Required Type Description

Request: POST /api/1/trading/new_order

Parameter Required Type Description

Summary: cancels an order. Returns ExecutionReport JSON object or CancelReject

Request: POST /api/1/trading/cancel_order

Parameter Required Type Description

Summary: cancels all orders. Returns ExecutionReport array of JSON object.

Request: POST /api/1/trading/cancel_orders

Parameter Required Type Description

Sample usage at HitBTC site: see https://hitbtc.com/terminal, My orders tab.

Request: GET /api/1/trading/orders/recent

Parameter Required Type Description

The following fields are used in order object:

Field Required Type Description

Summary: returns an array of user's orders (order objects).

Request: GET /api/1/trading/order

Parameter Required Type Description