NAV Navbar
shell python
  • MEET NEW VERSION OF HITBTC API!
  • DEVELOPMENT GUIDE
  • BEST PRACTICES
  • REST API Reference
  • Market data
  • Authentication
  • Trading
  • Trading history
  • Account management
  • Socket API Reference
  • Socket Market Data
  • Socket Session Authentication
  • Socket Trading
  • Errors
  • 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

    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

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

    API Explorer

    You can explore API using SwaggerUI including methods requiring authorization.

    API Sample code

    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
       },
       {
          "id": "ETH",
          "fullName": "Ethereum",
          "crypto": true,
          "payinEnabled": true,
          "payinPaymentId": false,
          "payinConfirmations": 2,
          "payoutEnabled": true,
          "payoutIsPaymentId": false,
          "transferEnabled": true
       }
    ]
    

    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)

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

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

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

    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

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

    Subscribe to Ticker

    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

    Subscribe to Orderbook

    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

    Subscribe to Trades

    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

    Subscribe to Candles

    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.

    Subscribe to reports

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

    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 }

    Errors

    The HitBTC API uses the following error codes:

    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