ABOUT 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.

By using HitBTC API you confirm that you have read and accept API License Agreement

DEVELOPMENT GUIDE

API Explorer

You can explore API using SwaggerUI including methods requiring authorization.

API Sample code & Libraries

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

RATE LIMITING

Rate Limits apply: * For the Market data, the limit is 100 requests/second per IP; * For Trading, the limit is 100 request/second per user; * For other requests, including Trading history, the limit is 10 requests/second per user.

Significant excess of the Rate Limits can lead to a suspend.

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

Market data

Currencies

curl "https://api.hitbtc.com/api/2/public/currency"

The above command returns JSON structured like this:

[
   {
      "id": "BTC",
      "fullName": "Bitcoin",
      "crypto": true,
      "payinEnabled": true,
      "payinPaymentId": false,
      "payinConfirmations": 2,
      "payoutEnabled": true,
      "payoutIsPaymentId": false,
      "transferEnabled": true,
      "delisted": false,
      "payoutFee": "0.00958"
   },
   {
      "id": "ETH",
      "fullName": "Ethereum",
      "crypto": true,
      "payinEnabled": true,
      "payinPaymentId": false,
      "payinConfirmations": 2,
      "payoutEnabled": true,
      "payoutIsPaymentId": false,
      "transferEnabled": true,
      "delisted": false,
      "payoutFee": "0.001"
   }
]

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)
delisted	Boolean	True if currency delisted (stopped deposit and trading)
payoutFee	Number	Default withdraw fee

Symbols

curl "https://api.hitbtc.com/api/2/public/symbol"

The above command returns JSON structured like this:

[      
  {
    "id": "ETHBTC",
    "baseCurrency": "ETH",
    "quoteCurrency": "BTC",
    "quantityIncrement": "0.001",
    "tickSize": "0.000001",
    "takeLiquidityRate": "0.001",
    "provideLiquidityRate": "-0.0001",
    "feeCurrency": "BTC"
  }
]

GET /api/2/public/symbol

GET /api/2/public/symbol/{symbol}

Return the actual list of currency symbols (currency pairs) traded on 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

Tickers

curl "https://api.hitbtc.com/api/2/public/ticker"

The above command returns JSON structured like this:

[
  {
    "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/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

Trades

curl "https://api.hitbtc.com/api/2/public/trades/ETHBTC?sort=DESC"

The above command returns JSON structured like this:

[
  {
    "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/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

Orderbook

curl "https://api.hitbtc.com/api/2/public/orderbook/ETHBTC"

The above command returns JSON structured like this:

{
  "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/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

Candles

curl "https://api.hitbtc.com/api/2/public/candles/ETHBTC?period=M30"

The above command returns JSON structured like this:

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

GET /api/2/public/candles/{symbol}

An candles used for OHLC a specific symbol.

Parameters:

Name	Type	Description
period	String	One of: M1 (one minute), M3, M5, M15, M30, H1, H4, D1, D7, 1M (one month). Default is M30 (30 minutes).
sort	String	Default ASC
from	Datetime
till	Datetime
limit	Number	Limit of candles, default 100.
offset	Number

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

Authentication

curl -u "publicKey:secretKey" https://api.hitbtc.com/api/2/trading/balance

import requests
session = requests.session()
session.auth = ("publicKey", "secretKey")

Public market data available without authentication, for other requests authentication is required.

You should create API keys on API Setting page. You can create multiple API keys with different permissions for your applications.

Use Basic Authentication to access REST API.

Trading

Trading Balance

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
     "https://api.hitbtc.com/api/2/trading/balance"

import requests
session = requests.session()
session.auth = ("ff20f250a7b3a414781d1abe11cd8cee", "fb453577d11294359058a9ae13c94713")
b = session.get('https://api.hitbtc.com/api/2/trading/balance').json()
print(b)

The above command returns JSON structured like this:

    [
      {
        "currency": "ETH",
        "available": "10.000000000",
        "reserved": "0.560000000"
      },
      {
        "currency": "BTC",
        "available": "0.010205869",
        "reserved": "0"
      }
    ]

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

Order model

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

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \ 
     "https://api.hitbtc.com/api/2/order"

import requests
session = requests.session()
session.auth = ("ff20f250a7b3a414781d1abe11cd8cee", "fb453577d11294359058a9ae13c94713")
b = session.get('https://api.hitbtc.com/api/2/order').json()
print(b)

The above command returns JSON structured like this:

[
  {
    "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

Return array of active orders.

Parameters:

Name	Type	Description
symbol	String	Optional parameter to filter active orders by symbol

Response: Array of orders

Get Active order by clientOrderId

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
     "https://api.hitbtc.com/api/2/order/c1837634ef81472a9cd13c81e7b91401"

import requests
session = requests.session()
session.auth = ("ff20f250a7b3a414781d1abe11cd8cee", "fb453577d11294359058a9ae13c94713")
// wait 20 sec for execution reports
b = session.get('https://api.hitbtc.com/api/2/order/c1837634ef81472a9cd13c81e7b91401?wait=20000').json()
print(b)

The above command returns JSON structured like this:

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

Create New Order

curl -X PUT -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/order/d8574207d9e3b16a4a5511753eeef175" \
    -d 'symbol=ETHBTC&side=sell&quantity=0.063&price=0.046016'

    import requests
    session = requests.session()
    session.auth = ("ff20f250a7b3a414781d1abe11cd8cee", "fb453577d11294359058a9ae13c94713")
    orderData = {'symbol':'ethbtc', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }
    r = session.post('https://api.hitbtc.com/api/2/order', data = orderData)
    print(r.json())

The above command returns JSON structured like this:

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

Error response example:

{
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  }
}

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

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

curl -X DELETE -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/order/d8574207d9e3b16a4a5511753eeef175"

The above command returns JSON structured like this:

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

DELETE /api/2/order/{clientOrderId}

Response: Order

Get trading commission

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/trading/fee/ETHBTC"

The above command returns JSON structured like this:

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

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

Get personal trading commission rate.

Trading history

Orders history

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/history/order?symbol=ETHBTC"

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

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/history/trades?symbol=ETHBTC"

[
  {
    "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/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

Trades by order

curl -X GET -u "ff20f250a7b3a414781d1abe11cd8cee:fb453577d11294359058a9ae13c94713" \
    "https://api.hitbtc.com/api/2/history/order/816088021/trades"

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

Account management

Account balance

[
  {
    "currency": "BTC",
    "available": "0.0504600",
    "reserved": "0.0000000"
  },
  {
    "currency": "ETH",
    "available": "30.8504600",
    "reserved": "0.0000000"
  }
]

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

Deposit crypto address

{
  "address": "NXT-G22U-BYF7-H8D9-3J27W",
  "paymentId": "616598347865"
}

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

Withdraw crypto

{
  "id": "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
}

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

Withdraw crypto commit or rollback

{
  "result": true
}

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

Transfer money between trading and account

{
  "id": "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
}

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

Get transactions history

[
  {
    "id": "6a2fb54d-7466-490c-b3a6-95d8c882f7f7",
    "index": 20400458,
    "currency": "ETH",
    "amount": "38.616700000000000000000000",
    "fee": "0.000880000000000000000000",
    "address": "0xfaEF4bE10dDF50B68c220c9ab19381e20B8EEB2B",        
    "hash": "eece4c17994798939cea9f6a72ee12faa55a7ce44860cfb95c7ed71c89522fe8",
    "status": "pending",
    "type": "payout",
    "createdAt": "2017-05-18T18:05:36.957Z",
    "updatedAt": "2017-05-18T19:21:05.370Z"
  }
]

GET /api/2/account/transactions

GET /api/2/account/transactions/{id} - get transaction by transaction id

Requires the "Payment information" API key permission.

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

Socket API Reference

Use JSON-RPC 2.0 over WebSocket connection as transport.

Request object

{
  "method": "newOrder",
  "params": {
    "clientOrderId": "57d5525562c945448e3cbd559bd068c4",
    "symbol": "ETHBTC",
    "side": "sell",
    "price": "0.059837",
    "quantity": "0.015"
  },
  "id": 123
}

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

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

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.

Server response for every request. On success subscription response is true. Example:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 123
}

Error response

{
  "jsonrpc": "2.0",
  "error": {
    "code": 2001,
    "message": "Symbol not found",
    "description": "Try get /api/2/public/symbol, to get list of all available symbols."
  },
  "id": 123
}

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

Socket 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.

Get Currencies

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "getCurrency",
  "params": {
    "currency": "ETH"
  },
  "id": 123
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "ETH",
    "fullName": "Ethereum",
    "crypto": true,
    "payinEnabled": true,
    "payinPaymentId": false,
    "payinConfirmations": 2,
    "payoutEnabled": true,
    "payoutIsPaymentId": false,
    "transferEnabled": true,
    "delisted": false,
    "payoutFee": "0.001"
  },
  "id": 123
}

Request methods: getCurrencies,getCurrency

{ "method": "getCurrency", "params": { "currency": "ETH" }, "id": 123 }

Get Symbols

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "getSymbol",
  "params": {
    "symbol": "ETHBTC"
  },
  "id": 123
}

Response

{
  "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: getSymbols,getSymbol

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "subscribeTicker",
  "params": {
    "symbol": "ETHBTC"
  },
  "id": 123
}

Notification ticker

{
  "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: subscribeTicker, unsubscribeTicker

Notification method: ticker

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "subscribeOrderbook",
  "params": {
    "symbol": "ETHBTC"
  },
  "id": 123
}

Notification snapshot

{
  "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"
      }
    ],
    "bid": [
      {
        "price": "0.054558",
        "size": "0.500"
      },
      {
        "price": "0.054557",
        "size": "0.076"
      },
      {
        "price": "0.054524",
        "size": "7.725"
      }
    ],
    "symbol": "ETHBTC",
    "sequence": 8073827
  }
}

Notification update

{
  "jsonrpc": "2.0",
  "method": "updateOrderbook",
  "params": {    
    "ask": [
      {
        "price": "0.054590",
        "size": "0.000"
      },
      {
        "price": "0.054591",
        "size": "0.000"
      }
    ],
    "bid": [
      {
        "price": "0.054504",
         "size": "0.000"
      }
    ],
    "symbol": "ETHBTC",
    "sequence": 8073830
  }
}

Request methods: subscribeOrderbook, unsubscribeOrderbook

Notification snapshot

Message contains a full snapshot of order book.

Notification method: snapshotOrderbook

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

Notification method: updateOrderbook

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "subscribeTrades",
  "params": {
    "symbol": "ETHBTC"
  },
  "id": 123
}

Request methods: subscribeTrades, unsubscribeTrades

Notification snapshot

{
  "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 method: snapshotTrades

Notification update

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

Notification method: updateTrades

Get Trades

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "getTrades",
  "params": {
    "symbol": "ETHBTC",
    "limit": 3,
    "sort": "DESC",
    "by": "id"
  },
  "id": 123
}

Response

{
  "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: getTrades

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

Request methods: subscribeCandles, unsubscribeCandles

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "subscribeCandles",
  "params": {
    "symbol": "ETHBTC",
    "period": "M30"
  },
  "id": 123
}

Notification snapshot

{
  "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 method: snapshotCandles

Notification update

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

Notification method: updateCandles

Socket Session Authentication

Example BASIC:


wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "login",
  "params": {
    "algo": "BASIC",
    "pKey": "3ef4a9f8c8bf04bd8f09884b98403eae",
    "sKey": "2deb570ab58fd553a4ed3ee249fd2d51"
  }
}

Example HS256:


wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "login",
  "params": {
    "algo": "HS256",
    "pKey": "3ef4a9f8c8bf04bd8f09884b98403eae",
    "nonce": "N1g287gL8YOwDZr",
    "signature": "b1c0ae399c2d341866a214f7d3ed755b821c1c36fc6f17083ef05fbb55b7f986"
  }
}

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

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.

wscat -c wss://api.hitbtc.com/api/2/ws

{
  "method": "subscribeReports",
  "params": {}
}

Notification with currently active orders

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

Method: subscribeReports

Method: activeOrders

Notification report

{
  "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: 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.

Place New Order

Request:

{
  "method": "newOrder",
  "params": {
    "clientOrderId": "57d5525562c945448e3cbd559bd068c4",
    "symbol": "ETHBTC",
    "side": "sell",
    "price": "0.059837",
    "quantity": "0.015"
  },
  "id": 123
}

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
}

Example error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": 20001,
    "message": "Insufficient funds",
    "description": "Check that the funds are sufficient, given commissions"
  },
  "id": 123
}

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 - GTC. 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`

Cancel Order

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

Method: cancelOrder

Example: { "method": "cancelOrder", "params": { "clientOrderId": "57d5525562c945448e3cbd559bd068c4" }, "id": 123 }

Cancel Replace Orders

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

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 }

Get active Orders

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

Get trading balance

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

Method: getTradingBalance

Example: { "method": "getTradingBalance", "params": {}, "id": 123 }

ABOUT HitBTC API

DEVELOPMENT GUIDE

API Explorer

API Sample code & Libraries

API URLs

DateTime Format

Number Format

Pagination

RATE LIMITING

BEST PRACTICES

HTTP Persistent Connection

Retrieving and updating account state

REST API Reference

HTTP Status codes

Error response

Market data

Currencies

Symbols

Tickers

Trades

Orderbook

Candles

Authentication

Trading

Trading Balance

Order model

Get Active orders

Get Active order by clientOrderId

Create New Order

Cancel orders

Cancel order by clientOrderId

Get trading commission

Trading history

Orders history

Trades history

Trades by order

Account management

Account balance

Deposit crypto address

Withdraw crypto

Withdraw crypto commit or rollback

Transfer money between trading and account

Get transactions history

Socket API Reference

Request object

Notification

Response object

Socket Market Data

Get Currencies

Get Symbols

Subscribe to Ticker

Subscribe to Orderbook

Subscribe to Trades

Get Trades

Subscribe to Candles

Socket Session Authentication

Socket Trading

Subscribe to reports

Place New Order

Cancel Order

Cancel Replace Orders

Get active Orders

Get trading balance