NAV

ABOUT HitBTC API

HitBTC REST & Streaming API version 3.0 provides programmatic access to HitBTC’s next generation trading engine.

We strongly recommend that our new customers use API version 3.0 to get the best trading experience. We also recommend that our current traders switch to the newest version 3.0.

API version 2.0 is still available. For detailed description refer to API v2.

By using the HitBTC API you confirm that you have read and accepted the API License Agreement.

DEVELOPMENT GUIDE

API URLs

REST https://api.hitbtc.com/api/3
Streaming Market Data wss://api.hitbtc.com/api/3/ws/public
Streaming Trading wss://api.hitbtc.com/api/3/ws/trading
Streaming Wallet wss://api.hitbtc.com/api/3/ws/wallet

Demo Environment (Sandbox):

REST https://api.demo.hitbtc.com/api/3
Streaming Market Data wss://api.demo.hitbtc.com/api/3/ws/public
Streaming Trading wss://api.demo.hitbtc.com/api/3/ws/trading
Streaming Wallet wss://api.demo.hitbtc.com/api/3/ws/wallet

API Explorer

You can explore the API using Swagger UI including methods requiring authorization.

DateTime Format

All timestamps are returned in ISO 8601 format or UNIX timestamp in milliseconds (UTC).

Example: "2024-04-03T10:20:49.315Z" or "1614815872000".

Date Format

Some timestamps are returned in ISO 8601 format which includes a calendar date only.

Example: "2024-04-03".

Number Format

All finance data, e.g., price, quantity, fee, etc., should be arbitrary precision numbers and have a string representation.

Example: "10.2000058".

Custom Formats

In nested JSON objects, child objects have custom formats which are described in tables below a place of the first occurrence.

Pagination

Parameter Description
limit Number of results per call.
offset Number of results offset.
sort Sort direction.
Accepted values: ASC (ascending order), DESC (descending order)
by Filter type.
Accepted values: id, timestamp
from Interval initial value.
If filter by timestamp is used, then parameter type is DateTime; otherwise — Number.
till Interval end value.
If filter by timestamp is used, then parameter type is DateTime; otherwise — Number.

RATE LIMITS

The maximum number requests per second (RPS) for specific calls can be limited by a rate limit and a burst limit.

The server will process a number of requests that do not exceed the sum of the rate limit and the burst limit within the 1-second sliding window.

If both limits in total are exceeded, an HTTP 429 response is returned.

Requests are being counted per call (REST endpoint or WebSocket message) and:

Per IP Address

REST API

Path Rate limit Burst limit
/* (default) 20 30
/public/* 30 50
/wallet/* 10 10
/spot/order/* 300 450
/margin/order/*,
/margin/account/*,
/margin/position/*
300 450
/futures/order/*,
/futures/account/*,
/futures/position/*
300 450
/transfer-convert/config 10 10

Socket API

Path Rate limit Burst limit
/ws/public 10 10
/ws/trading 10 10
/ws/wallet 10 10

Per Account

Order Limits

The total number of user's active and suspended orders cannot exceed 25000 across all symbols and 2000 — for a particular symbol.

After the limit is reached, new order requests will be rejected.

REST API

Path Rate limit Burst limit
/wallet/*,
/transfer-convert/config
20 30
/sub-account/* 20 30

Socket API

/ws/trading:

Method Rate limit Burst limit
login 5
spot_subscribe,
spot_unsubscribe,
spot_balance_subscribe,
spot_balance_unsubscribe
5
margin_subscribe, margin_unsubscribe 5
futures_subscribe,
futures_unsubscribe,
futures_balance
5
spot_balances,
spot_fee
20 10
margin_get_accounts 20 10
futures_get_accounts,
futures_balances,
futures_fee
20 10
spot_new_order,
spot_new_order_list,
spot_replace_order
300 200
margin_new_order,
margin_new_order_list,
margin_replace_order
300 200
futures_new_order,
futures_new_order_list,
futures_replace_order
300 200

/ws/wallet:

Method Rate limit Burst limit
login 2 10
subscribe_transactions,
unsubscribe_transactions,
subscribe_wallet_balances,
unsubscribe_wallet_balances,
wallet_balances,
wallet_balance,
transactions
5 10

CHANGELOG

29.11.2024

22.10.2024

02.10.2024

04.09.2024

17.05.2024

15.05.2024

10.05.2024

05.03.2024

Added new 20018 error code.

01.02.2024

02.11.2023

Added support of multichain that allows specifying a combination of a currency and a base blockchain:

09.10.2023

Added the commit risk score in the transaction history for deposits.

25.09.2023

Added a new operation_type field in the transaction history.

25.07.2023

Changed default TIF instructions for new orders.

07.07.2023

A new GET /api/3/wallet/crypto/fees/estimate endpoint.

22.06.2023

Cross-margin accounts.

31.05.2023

A new preferred_network filter in the GET /api/3/public/currency endpoint.

19.05.2023

WebSocket price/rate/ feeds.

15.11.2022

WebSocket balance feed.

28.07.2022

One-Triggers-Other (OTO) order lists.

16.03.2022

12.01.2022

Cash-settled futures.

27.12.2021

Take-profit orders.

23.12.2021

Reduce-only orders.

08.12.2021

Margin parameters.

23.11.2021

Amount locks.

19.11.2021

10.11.2021

25.08.2021

Airdrops section.

24.08.2021

30.07.2021

28.07.2021

API v3 initial release.

BEST PRACTICES

The HitBTC API development team strives to bring the best trading experience to API users. This manual contains a set of best practices for using the API as efficiently as possible.

Request Parameters

Pass a request payload (body) in POST requests and query parameters — in GET requests.

Passing parameters in a way different from the documentation is not supported.

HTTP Persistent Connection

The underlying TCP connection is kept active for multiple requests/responses. Subsequent requests will result in reduced latency as the TCP handshaking process is no longer required.

If you use the HTTP 1.0 client, please ensure it supports the Keep-Alive directive and submit the "Connection: Keep-Alive" header with a request.

Keep-Alive is a part of the HTTP/1.1 or HTTP/2 protocol and enabled by default on compliant clients. However, you will have to ensure your implementation does not set other values as the connection header.

Retrieving and Updating Account State

Use the Streaming API for real-time updates of orders, trades, and any transaction changes.

REST API REFERENCE

HTTP Status Codes

Error Response

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

All error responses have error code and human-readable message fields. Some errors contain an additional description field.

Market Data

Currencies

Get Currencies

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

Response:

{
  "BTC":
  {
    "full_name": "test",
    "crypto": true,
    "payin_enabled": true,
    "payout_enabled": true,
    "transfer_enabled": true,
    "sign": "฿",
    "qr_prefix": "bitcointestnet:",
    "crypto_payment_id_name": "",
    "crypto_explorer": "https://blockchain.info/tx/{tx}",
    "precision_transfer": "1",
    "delisted": false,
    "networks": [
      {
        "code": "test123",
        "network": "test",
        "protocol": "test123",
        "default": true,
        "is_ens_available": true,
        "payin_enabled": true,
        "payout_enabled": true,
        "precision_payout": "1",
        "payout_fee": "0.000000000000",
        "payout_is_payment_id": false,
        "payin_payment_id": false,
        "payin_confirmations": 3
      }
    ]
  },
  "ETH":
  {
    "full_name": "Ethereum TST",
    "crypto": true,
    "payin_enabled": true,
    "payout_enabled": true,
    "transfer_enabled": true,
    "sign": "E",
    "qr_prefix": "ethereum:",
    "crypto_payment_id_name": "",
    "crypto_explorer": "https://www.etherchain.org/tx/{tx}",
    "precision_transfer": "0.000000000001",
    "delisted": false,
    "networks": [
      {
        "code": "ETHTEST",
        "network_name": "ETHTEST",
        "network": "ETHTEST",
        "protocol": "",
        "default": true,
        "is_ens_available": true,
        "payin_enabled": true,
        "payout_enabled": true,
        "precision_payout": "0.000000000000000001",
        "payout_fee": "0.000000000000",
        "payout_is_payment_id": false,
        "payin_payment_id": false,
        "payin_confirmations": 2,
        "is_multichain": false
      }
    ]
  }
}

GET /api/3/public/currency

Returns the actual list of available currencies, tokens, etc.

Requires no API key Access Rights.

Parameters:

Name Type Description
currencies String Optional. Comma-separated list of currency codes.
preferred_network String Optional. Code of the default network for currencies.

Response:

Name Type Description
full_name String Currency full name (e.g., "Bitcoin").
crypto Boolean Flag indicating whether the currency is a cryptocurrency.
payin_enabled Boolean Flag indicating whether generating deposit addresses is allowed for the currency.
payout_enabled Boolean Flag indicating whether withdrawals are allowed for the currency.
transfer_enabled Boolean Flag indicating whether transfers between the bank and the exchange accounts are allowed for the network (may be disabled on maintenance).
sign String Currency sign.
crypto_payment_id_name String The name of an additional account identifier used for the protocol.
crypto_explorer String The link to the currency explorer with "{tx}" placeholder instead of a hash.
precision_transfer Number The minimum amount of a transfer.
account_top_order Number Optional. The absolute position of the currency in the currency list.
qr_prefix String The QR prefix used for indication of the currency in a deposit address.
delisted Boolean Flag indicating whether the currency has been delisted.
networks []Network Networks that may host operations on the currency.

Network model consists of:

Name Type Description
code String Currency code.
network_name String Full network name.
network String Code of the currency of the hosting network.
is_ens_available Boolean Flag indicating whether the network supports ENS (Ethereum Name Service).
protocol String Optional. The standard or protocol underlying network operations or smart contracts.
If equals code, the currency is the network native currency.
If "TOKEN", the currency is a token build on top of this layer-2 network.
Example: "ERC20"
default Boolean Flag indicating whether the network is the default for the currency.
payin_enabled Boolean Flag indicating whether generating deposit addresses is allowed for the network.
payout_enabled Boolean Flag indicating whether withdrawals are allowed for the network.
precision_payout Number The minimum amount of a withdrawal.
payout_fee Number Optional. The minimal possible fee value constituted of the network fee charged by a blockchain and the maintenance fee charged by the exchange.
payout_is_payment_id Boolean Flag indicating whether providing additional information for withdrawals is needed.
payin_payment_id Boolean Flag indicating whether providing additional information for deposits is needed.
payin_confirmations Number The number of confirmation needed for a transaction to be accepted in the network.
address_regex String Optional. Regular expression to a deposit address.
payment_id_regex String Optional. Regular expression for a payment identifier.
low_processing_time Number Optional. The lowest processing time in seconds for a withdrawal.
high_processing_time Number Optional. The highest processing time in seconds for a withdrawal.
avg_processing_time Number Optional. The average processing time in seconds for a withdrawal.
crypto_payment_id_name String Optional. Transaction identifier, e.g., comment, message, memo, attachment, etc.
crypto_explorer String Optional. The link to the network explorer with "{tx}" placeholder instead of a hash.
contract_address String Token contract address.
is_multichain Boolean Flag indicating whether multichain is active for the network.
asset_id JSON Optional. A unique arbitrary object that identifies a coin. Each network has its own set of properties returned inside the object.

Get Currency

curl "https://api.hitbtc.com/api/3/public/currency/BTC"

Response:

{
  "full_name": "test",
  "crypto": true,
  "payin_enabled": true,
  "payout_enabled": true,
  "transfer_enabled": true,
  "sign": "฿",
  "qr_prefix": "bitcointestnet:",
  "crypto_payment_id_name": "",
  "crypto_explorer": "https://blockchain.info/tx/{tx}",
  "precision_transfer": "1",
  "delisted": false,
  "networks": [
    {
      "code": "test123",
      "network_name": "test123",
      "network": "test",
      "protocol": "test123",
      "default": true,
      "is_ens_available": true,
      "payin_enabled": true,
      "payout_enabled": true,
      "precision_payout": "1",
      "payout_fee": "0.000000000000",
      "payout_is_payment_id": false,
      "payin_payment_id": false,
      "payin_confirmations": 3,
      "is_multichain": false
    }
  ]
}

GET /api/3/public/currency/{currency}

Returns the data for a certain currency.

Requires no API key Access Rights.

Response:

Name Type Description
full_name String Currency full name (e.g., "Bitcoin").
crypto Boolean Flag indicating whether the currency is a cryptocurrency.
payin_enabled Boolean Flag indicating whether generating deposit addresses is allowed for the currency.
payout_enabled Boolean Flag indicating whether withdrawals are allowed for the currency.
transfer_enabled Boolean Flag indicating whether transfers between the bank and the exchange accounts are allowed for the network (may be disabled on maintenance).
sign String Currency sign.
crypto_payment_id_name String The name of an additional account identifier used for the protocol.
crypto_explorer String The link to the currency explorer with "{tx}" placeholder instead of a hash.
precision_transfer Number The minimum amount of a transfer.
account_top_order Number Optional. The absolute position of the currency in the currency list.
qr_prefix String The QR prefix used for indication of the currency in a deposit address.
delisted Boolean Flag indicating whether the currency has been delisted.
networks []Network Networks that may host operations on the currency.

Symbols

Get Symbols

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

Response:

{
  "ETHBTC": {
    "type": "spot",
    "base_currency": "ETH",
    "quote_currency": "BTC",
    "status": "working",
    "quantity_increment": "0.001",
    "tick_size": "0.000001",
    "take_rate": "0.001",
    "make_rate": "-0.0001",
    "fee_currency": "BTC",
    "margin_trading": true,
    "max_initial_leverage": "10.00"
  }
}

GET /api/3/public/symbol

Returns 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

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of symbol codes.

Response:

Name Type Description
type String Symbol type.
Possible values: spot, futures
contract_type String Contract type.
Possible values: perpetual, cash_settled
expiry DateTime or null Futures expiration date.
null for perpetual contracts.
underlying String Futures contract underlying asset.
base_currency String or null Name (code) of base currency, (e.g., "ETH"). For futures contracts is null.
quote_currency String Name (code) of quote currency.
status String Exchange status.
Possible values: working, suspended, clearing
quantity_increment Number Symbol quantity should be divided by this value with no remainder.
tick_size Number Symbol price should be divided by this value with no remainder.
take_rate Number Default fee rate.
make_rate Number Default fee rate for market making trades.
fee_currency String Currency in which fees are determined.
margin_trading Boolean Whether margin trading is available.
max_initial_leverage Number Optional. Maximum leverage that the user can use for margin trading. Shown only if margin_trading is true.

Get Symbol

curl "https://api.hitbtc.com/api/3/public/symbol/ETHBTC"

Response:

{
  "type": "spot",
  "base_currency": "ETH",
  "quote_currency": "BTC",
  "status": "working",
  "quantity_increment": "0.0001",
  "tick_size": "0.000001",
  "take_rate": "0.002",
  "make_rate": "0.001",
  "fee_currency": "BTC",
  "margin_trading": true,
  "max_initial_leverage": "10.00"
}

GET /api/3/public/symbol/{symbol}

Returns the data for a certain symbol.

Requires no API key Access Rights.

Response:

Name Type Description
type String Symbol type.
Possible values: spot, futures
contract_type String Contract type.
Possible values: perpetual, cash_settled
expiry DateTime or null Futures expiration date.
null for perpetual contracts.
underlying String Futures contract underlying asset.
base_currency String or null Name (code) of base currency, (e.g., "ETH"). For futures contracts is null.
quote_currency String Name (code) of quote currency.
status String Exchange status.
Possible values: working, suspended, clearing
quantity_increment Number Symbol quantity should be divided by this value with no remainder.
tick_size Number Symbol price should be divided by this value with no remainder.
take_rate Number Default fee rate.
make_rate Number Default fee rate for market making trades.
fee_currency String Currency in which fees are determined.
margin_trading Boolean Whether margin trading is available.
max_initial_leverage Number Optional. Maximum leverage that the user can use for margin trading. Shown only if margin_trading is true.

Tickers

Get Tickers

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

Response:

{
  "ETHBTC": {
    "ask": "0.050043",
    "bid": "0.050042",
    "last": "0.050042",
    "low": "0.047052",
    "high": "0.051679",
    "open": "0.047800",
    "volume": "36456.720",
    "volume_quote": "1782.625000",
    "timestamp": "2024-04-12T14:57:19.999Z"
  }
}

GET /api/3/public/ticker

Returns ticker information.

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols String Optional. Comma-separated list of symbol codes.

Response:

Name Type Description
ask Number or null Best ask price. Can return null if no data.
bid Number or null Best bid price. Can return null if no data.
last Number or null Last trade price. Can return null if no data.
low Number The lowest trade price within 24 hours.
high Number The highest trade price within 24 hours.
open Number or null Last trade price 24 hours ago. Can return null if no data.
volume Number Total trading amount within 24 hours in base currency.
volume_quote Number Total trading amount within 24 hours in quote currency.
timestamp DateTime Last update or refresh ticker timestamp.

Get Ticker by Symbol

curl "https://api.hitbtc.com/api/3/public/ticker/ETHBTC"

Response:

{
  "ask": "0.020572",
  "bid": "0.020566",
  "last": "0.020574",
  "low": "0.020388",
  "high": "0.021084",
  "open": "0.020913",
  "volume": "138444.3666",
  "volume_quote": "2853.6874972480",
  "timestamp": "2024-04-02T17:52:36.731Z"
}

GET /api/3/public/ticker/{symbol}

Returns the ticker for a certain symbol.

Requires no API key Access Rights.

Response:

Name Type Description
ask Number or null Best ask price. Can return null if no data.
bid Number or null Best bid price. Can return null if no data.
last Number or null Last trade price. Can return null if no data.
low Number The lowest trade price within 24 hours.
high Number The highest trade price within 24 hours.
open Number or null Last trade price 24 hours ago. Can return null if no data.
volume Number Total trading amount within 24 hours in base currency.
volume_quote Number Total trading amount within 24 hours in quote currency.
timestamp DateTime Last update or refresh ticker timestamp.

Prices

Get Prices

curl "https://api.hitbtc.com/api/3/public/price/rate?from=ETH&to=BTC"

Response:

{
  "ETH":{
    "currency": "BTC",
    "price": "0.021084",
    "timestamp": "2024-04-02T17:52:36.731Z"
  }
}

GET /api/3/public/price/rate

Returns the mean of "best" bid price and "best" ask price in the order book.

Requires no API key Access Rights.

Parameters:

Name Type Description
from String Source currency code.
to String Target currency code.

Response:

Name Type Description
currency String Quote currency code.
price Number Quotation price.
timestamp DateTime Last update or refresh price timestamp.

Get Prices History

curl "https://api.hitbtc.com/api/3/public/price/history?from=ETH&to=BTC"

Response:

{
  "ETH":{
    "currency": "BTC",
    "history": [
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "0.063420",
      "close": "0.063767",
      "min": "0.063403",
      "max": "0.063782"
    }
  ]
}

GET /api/3/public/price/history

Returns quotation prices history.

Requires no API key Access Rights.

Parameters:

Name Type Description
from String Source currency code.
to String Target currency code.
until DateTime Optional. Interval end value.
since DateTime Optional. Interval initial value.
limit Number Optional
Default value: 1
Accepted values: 11000
period String Optional. Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
sort String Optional. Sort direction.
Accepted values: ASC, DESC
Default value: DESC

Response:

Name Type Description
currency String Quote currency code.
history History Quotation price history entry.

History model consists of:

Name Type Description
timestamp DateTime Last update or refresh price timestamp.
open Number Open price.
close Number Closing price.
min Number The lowest price for the period.
max Number The highest price for the period.

Get Ticker Last Prices

curl "https://api.hitbtc.com/api/3/public/price/ticker"

Response:

{
  "ETHBTC": {
    "price": "0.050042",
    "timestamp": "2024-04-12T14:57:19.999Z"
  }
}

GET /api/3/public/price/ticker

Returns tickers' last prices for all symbols.

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols String Optional. Comma-separated list of symbol codes.

Response:

Name Type Description
price Number Ticker last price.
timestamp DateTime Last update or refresh ticker timestamp.

Get Ticker Last Price by Symbol

curl "https://api.hitbtc.com/api/3/public/price/ticker/ETHBTC"

Response:

{
  "price": "0.021084",
  "timestamp": "2024-04-02T17:52:36.731Z"
}

GET /api/3/public/price/ticker/{symbol}

Returns the ticker last price for a certain symbol.

Requires no API key Access Rights.

Response:

Name Type Description
price Number Ticker last price.
timestamp DateTime Last update or refresh ticker timestamp.

Trades

Get Trades

curl "https://api.hitbtc.com/api/3/public/trades"

Response:

{
  "BTCUSDT":[
    {
      "id":3494,
      "price":"9793.94",
      "qty":"0.21469",
      "side":"sell",
      "timestamp":"2024-04-24T12:54:41.972Z"
    }
  ],
  "ETHBTC":[
    {
      "id":3495,
      "price":"0.027668",
      "qty":"0.069",
      "side":"buy",
      "timestamp":"2024-04-24T12:54:32.843Z"
    }
  ]
}

GET /api/3/public/trades

Returns trades information for all or multiple symbols.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of symbol codes.
by String Filter type.
Accepted values: id, timestamp
Default value: timestamp
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime or Number Interval initial value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
till DateTime or Number Interval end value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
id Number Trade identifier.
price Number Trade price.
qty Number Trade quantity.
side String Trade side.
Accepted values: sell, buy
timestamp DateTime Trade timestamp.

Get Trades by Symbol

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

Response:

[
  {
    "id": 9533117,
    "price": "0.046001",
    "qty": "0.220",
    "side": "sell",
    "timestamp": "2024-04-14T12:18:40.426Z"
  },
  {
    "id": 9533116,
    "price": "0.046002",
    "qty": "0.022",
    "side": "buy",
    "timestamp": "2024-04-14T11:56:37.027Z"
  }
]

GET /api/3/public/trades/{symbol}

Returns trades information for a certain symbol.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
by String Filter type.
Accepted values: id, timestamp
Default value: timestamp
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime or Number Optional. Interval initial value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
till DateTime or Number Optional. Interval end value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
id Number Trade identifier.
price Number Trade price.
qty Number Trade quantity.
side String Trade side.
Possible values: sell, buy
timestamp DateTime Trade timestamp.

Order Books

Get Order Books

curl "https://api.hitbtc.com/api/3/public/orderbook"

Response:

{
  "BTCUSDT": {
    "timestamp": "2024-04-11T11:18:03.857366871Z",
    "ask": [
      [
        "9777.51",                       // Price
        "4.50579"                        // Amount
      ],
      [
        "9777.52",
        "5.79832"
      ]
    ],
    "bid": [
      [
        "9777.5",
        "0.00002"
      ],
      [
        "9776.26",
        "0.0001"
      ]
    ]
  },
  "ETHBTC": {
    "timestamp": "2024-04-11T11:18:03.790858502Z",
    "ask": [
      [
        "0.022626",
        "0.0057"
      ],
      [
        "0.022628",
        "1.4259"
      ]
    ],
    "bid": [
      [
        "0.022624",
        "0.5748"
      ],
      [
        "0.022623",
        "26.5"
      ]
    ]
  }
}

GET /api/3/public/orderbook

An Order Book is a list of buy and sell orders for a specific symbol, structured by price level.

Requires no API key Access Rights.

Parameters:

Name Type Description
depth Number Optional. Order Book depth.
Default value: 10
Set to 0 to view the full Order Book.
symbols String Optional. Comma-separated list of symbol codes.

Response:

Name Type Description
timestamp DateTime Publication timestamp.
ask []String Ask side array of levels.
bid []String Bid side array of levels.

Get Order Book by Symbol

curl "https://api.hitbtc.com/api/3/public/orderbook/ETHBTC?volume=0.5"

Response:

{
  "timestamp": "2024-04-11T11:30:38.597950917Z",
  "ask": [
     [
        "9779.68",                       // Price
        "2.497"                          // Quantity
      ]
    ],
  "bid": [
    [
      "9779.67",
      "0.03719"
    ],
    [
      "9779.29",
      "0.171"
    ],
    [
      "9779.27",
      "0.171"
    ],
    [
      "9779.21",
      "0.171"
    ]
  ]
}

GET /api/3/public/orderbook/{symbol}

The request returns an Order Book for a certain symbol.

Requires no API key Access Rights.

Parameters:

Name Type Description
depth Number Optional. Order Book depth.
Default value: 100
Set to 0 to view the full Order Book.
volume Number Optional. Desired volume for market depth search.

Please note that if the volume is specified, the depth will be ignored.

Response:

Name Type Description
timestamp DateTime Publication timestamp.
ask []String Ask side array of levels.
bid []String Bid side array of levels.

Candles

Get Candles

curl "https://api.hitbtc.com/api/3/public/candles"

Response:

{
  "BTCUSDT":[
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "33079.93",
      "close": "33236.53",
      "min": "33079.93",
      "max": "33295.73",
      "volume": "146.86223",
      "volume_quote": "4877838.3025063"
    }
  ],
  "ETHBTC":[
    {
      "timestamp": "2021-07-01T20:00:00.000Z",
      "open": "0.063420",
      "close": "0.063767",
      "min": "0.063403",
      "max": "0.063782",
      "volume": "866.6776",
      "volume_quote": "55.2132903904"
    }
  ]
}

GET /api/3/public/candles

Candles are used for the representation of a specific symbol as an OHLC chart.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of symbol codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open price.
close Number Closing price.
min Number The lowest price for the period.
max Number The highest price for the period.
volume Number Volume in base currency.
volume_quote Number Volume in quote currency.

Get Candles by Symbol

curl "https://api.hitbtc.com/api/3/public/candles/ETHBTC"

Response:

[
  {
    "timestamp": "2024-04-20T20:00:00.000Z",
    "open": "0.050459",
    "close": "0.050087",
    "min": "0.050000",
    "max": "0.050511",
    "volume": "1326.628",
    "volume_quote": "66.555987736"
  },
  {
    "timestamp": "2024-04-20T20:30:00.000Z",
    "open": "0.050108",
    "close": "0.050139",
    "min": "0.050068",
    "max": "0.050223",
    "volume": "87.515",
    "volume_quote": "4.386062831"
  }
]

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

Returns candles for a certain symbol.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open price.
close Number Closing price.
min Number The lowest price for the period.
max Number The highest price for the period.
volume Number Volume in base currency.
volume_quote Number Volume in quote currency.

Get Converted Candles

curl "https://api.hitbtc.com/api/3/public/converted/candles?target_currency=USDT"

Response:

{
  "target_currency": "USDT",
  "data": {
    "BTCUSDT": [
      {
        "timestamp": "2024-02-01T10:30:00.000Z",
        "open": "42265.17",
        "close": "42196.10",
        "min": "42182.49",
        "max": "42269.15",
        "volume": "60.88187",
        "volume_quote": "2569178.2573316"
      }
    ],
    "ETHBTC": [
      {
        "timestamp": "2024-02-01T10:30:00.000Z",
        "open": "2270.91293888",
        "close": "2268.00140384",
        "min": "2267.70603072",
        "max": "2271.50368512",
        "volume": "13.6669",
        "volume_quote": "31032.101773456736"
      }
    ]
  }
}

GET /api/3/public/converted/candles

Returns OHLCV data regarding the last price converted to the target currency for all symbols.

Candles are used for the representation of a specific symbol as an OHLC chart.

Requires no API key Access Rights.

Parameters:

Name Type Description
target_currency String Target currency for conversion.
symbols String Comma-separated list of symbol codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
target_currency String Target currency for conversion.
data Map Candles converted to the target currency.
> []JSON Symbol code.
>> timestamp DateTime Candle timestamp.
>> open Number Open price.
>> close Number Closing price.
>> min Number The lowest price for the period.
>> max Number The highest price for the period.
>> volume Number Volume in base currency.
>> volume_quote Number Volume in quote currency.

Get Converted Candles by Symbol

curl "https://api.hitbtc.com/api/3/public/converted/candles/ETHBTC?target_currency=USDT"

Response:

{
  "target_currency": "USDT",
  "data": [
    {
      "timestamp": "2024-02-01T10:30:00.000Z",
      "open": "2270.614518070",
      "close": "2267.450221945",
      "min": "2267.365840715",
      "max": "2271.205186680",
      "volume": "13.7525",
      "volume_quote": "31222.1126879271435"
    }
  ]
}

GET /api/3/public/converted/candles/{symbol}

Returns OHLCV data regarding the last price converted to the target currency for a symbol.

All parameters are optional.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
target_currency String Target currency for conversion.
data []JSON Candles converted to the target currency.
> timestamp DateTime Candle timestamp.
> open Number Open price.
> close Number Closing price.
> min Number The lowest price for the period.
> max Number The highest price for the period.
> volume Number Volume in base currency.
> volume_quote Number Volume in quote currency.

Futures Info

Get Futures Information

curl "https://api.hitbtc.com/api/3/public/futures/info"

Response:

{
  "UFO-1217": {
    "contract_type": "cash_settled",
    "mark_price": "1.21838",
    "index_price": "1.21838",
    "open_interest": "0",
    "indicative_settlement_price": "1.22421",
    "expiry": "2021-12-17T14:00:00.000Z",
    "timestamp": "2021-12-17T14:00:01.062Z"
  },
  "BTCUSDT_PERP": {
    "contract_type": "perpetual",
    "mark_price": "30897.68",
    "index_price": "30895.29",
    "funding_rate": "0.0001",
    "open_interest": "93.7128",
    "next_funding_time": "2021-07-21T16:00:00.000Z",
    "indicative_funding_rate": "0.0001",
    "premium_index": "0.000047541807127312",
    "avg_premium_index": "0.000087063368020112",
    "interest_rate": "0.0001",
    "timestamp": "2021-07-21T09:48:37.235Z"
  },
  "EOSETH_PERP": {
    "contract_type": "perpetual",
    "mark_price":"0.0020600",
    "index_price":"0.0020600",
    "funding_rate":"0.0001",
    "open_interest":"60.6580",
    "next_funding_time":"2024-04-25T16:00:00.000Z",
    "indicative_funding_rate":"0.0001",
    "premium_index":"0.1045547",
    "avg_premium_index":"0.1004467",
    "interest_rate": "0.0001",
    "timestamp":"2024-04-25T14:43:20.079Z"
  }
}

GET /api/3/public/futures/info

Returns futures information for all or multiple contracts.

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols String Optional. Comma-separated list of contract codes.

Response:

Name Type Description
contract_type String Contract type.
Possible values: perpetual, cash_settled
mark_price Number Recent asset price adjusted by the value of fair basis.
index_price Number Average underlying asset price.
funding_rate Number Optional. Percent of the contract's mark value paid in the previous funding period. Returned only if contract_type is perpetual.
open_interest Number Total quantity of traded futures contracts.
next_funding_time DateTime Optional. Timestamp of the next funding. Returned only if contract_type is perpetual.
indicative_funding_rate Number Optional. Estimated percent of the contract's mark value to be paid after the end of the current funding period, calculated at the moment. Returned only if contract_type is perpetual.
premium_index Number Optional. Time-weighted average over premium indexes from the previous funding to the moment. Used during calculation of indicative_funding_rate. Returned only if contract_type is perpetual.
avg_premium_index Number Optional. Time-weighted average over premium indexes for previous funding period. Used during calculation of funding_rate for adjusting it to the deviation of contract market price from the mark price. Returned only if contract_type is perpetual.
interest_rate Number Optional. Contract interest rate for one funding period.
indicative_settlement_price Number Optional. Expected price of closing position on a cash settled contract. Calculated during the last 30 minutes prior to contract expiration — until that, equals to index_price. Returned only if contract_type is cash_settled.
expiry DateTime Optional. Contract expiration date. Returned only if contract_type is cash_settled.
timestamp DateTime Request timestamp.

Get Futures Information for Contract

curl "https://api.hitbtc.com/api/3/public/futures/info/BTCUSDT_PERP"

Response:

{
  "BTCUSDT_PERP": {
    "contract_type": "perpetual",
    "mark_price": "30897.68",
    "index_price": "30895.29",
    "funding_rate": "0.0001",
    "open_interest": "93.7128",
    "next_funding_time": "2021-07-21T16:00:00.000Z",
    "indicative_funding_rate": "0.0001",
    "premium_index": "0.000047541807127312",
    "avg_premium_index": "0.000087063368020112",
    "interest_rate": "0.0001",
    "timestamp": "2021-07-21T09:48:37.235Z"
  }
}

GET /api/3/public/futures/info/{symbol}

Returns futures information for a specified contract.

Requires no API key Access Rights.

Response:

Name Type Description
contract_type String Contract type.
Possible values: perpetual, cash_settled
mark_price Number Recent asset price adjusted by the value of fair basis.
index_price Number Average underlying asset price.
funding_rate Number Optional. Percentage of contract mark value paid after the end of current funding interval. Returned only if contract_type is perpetual.
open_interest Number Total quantity of traded futures contracts.
next_funding_time DateTime Optional. Timestamp of the next funding. Returned only if contract_type is perpetual.
indicative_funding_rate Number Optional. Estimated percent of the contract's mark value to be paid after the end of the current funding period, calculated at the moment. Returned only if contract_type is perpetual.
premium_index Number Optional. Time-weighted average over premium indexes from the previous funding to the moment. Used during calculation of indicative_funding_rate. Returned only if contract_type is perpetual.
avg_premium_index Number Optional. Time-weighted average over premium indexes for previous funding period. Used during calculation of funding_rate for adjusting it to the deviation of contract market price from the mark price. Returned only if contract_type is perpetual.
interest_rate Number Optional. Contract interest rate for one funding period.
indicative_settlement_price Number Optional. Expected price of closing position on a cash settled contract. Calculated during the last 30 minutes prior to contract expiration — until that, equals to index_price. Returned only if contract_type is cash_settled.
expiry DateTime Optional. Contract expiration date. Returned only if contract_type is cash_settled.
timestamp DateTime Request timestamp.

Funding History

Get Funding History

curl "https://api.hitbtc.com/api/3/public/futures/history/funding"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-29T16:00:00.271Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000061858585213222",
      "next_funding_time": "2021-07-30T00:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T08:00:00.506Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000064275104721498",
      "next_funding_time": "2021-07-29T16:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T00:00:00.233Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000025719039726718",
      "next_funding_time": "2021-07-29T08:00:00.000Z",
      "interest_rate": "0.0001"
    }
  ]
}

GET /api/3/public/futures/history/funding

Returns funding history for specified perpetual contracts or all of those.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of symbol codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Request timestamp.
funding_rate String Percentage of contract mark value paid after the end of current funding interval.
avg_premium_index String Time-weighted average over premium indexes for previous funding period. Used during calculation of funding_rate for adjusting it to the deviation of contract market price from the mark price.
next_funding_time DateTime Timestamp of the next funding.
interest_rate String Contract interest rate for one funding period.

Get Funding History for Contract

curl "https://api.hitbtc.com/api/3/public/futures/history/funding/BTCUSDT_PERP"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-29T16:00:00.271Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000061858585213222",
      "next_funding_time": "2021-07-30T00:00:00.000Z",
      "interest_rate": "0.0001"
    },
    {
      "timestamp": "2021-07-29T08:00:00.506Z",
      "funding_rate": "0.0001",
      "avg_premium_index": "0.000064275104721498",
      "next_funding_time": "2021-07-29T16:00:00.000Z",
      "interest_rate": "0.0001"
    }
  ]
}

GET /api/3/public/futures/history/funding/{symbol}

Returns funding history for a specified perpetual contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Request timestamp.
funding_rate String Percent of the contract's mark value paid in the previous funding period.
avg_premium_index String Time-weighted average over premium indexes for previous funding period. Used during calculation of funding_rate for adjusting it to the deviation of contract market price from the mark price.
next_funding_time DateTime Timestamp of the next funding.
interest_rate String Contract interest rate for one funding period.

Futures Index Price Candles

Get Index Price Candles

curl "https://api.hitbtc.com/api/3/public/futures/candles/index_price"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T07:30:00.000Z",
      "open": "32414.58",
      "close": "32414.58",
      "min": "32414.58",
      "max": "32414.58"
    },
    {
      "timestamp": "2021-07-07T18:00:00.000Z",
      "open": "34748.31",
      "close": "34748.31",
      "min": "34748.31",
      "max": "34748.31"
    },
    {
      "timestamp": "2021-07-07T12:30:00.000Z",
      "open": "34777.96",
      "close": "34777.96",
      "min": "34777.96",
      "max": "34777.96"
    }
  ]
}

GET /api/3/public/futures/candles/index_price

Returns index price candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of contract codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open index price.
close Number Closing index price.
min Number The lowest index price for the period.
max Number The highest index price for the period.

Get Index Price Candles by Contract

curl "https://api.hitbtc.com/api/3/public/futures/candles/index_price/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T07:30:00.000Z",
    "open": "32414.58",
    "close": "32414.58",
    "min": "32414.58",
    "max": "32414.58"
  },
  {
    "timestamp": "2021-07-07T18:00:00.000Z",
    "open": "34748.31",
    "close": "34748.31",
    "min": "34748.31",
    "max": "34748.31"
  },
  {
    "timestamp": "2021-07-07T12:30:00.000Z",
    "open": "34777.96",
    "close": "34777.96",
    "min": "34777.96",
    "max": "34777.96"
  }
]

GET /api/3/public/futures/candles/index_price/{symbol}

Returns index price candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open index price.
close Number Closing index price.
min Number The lowest index price for the period.
max Number The highest index price for the period.

Futures Mark Price Candles

Get Mark Price Candles

curl "https://api.hitbtc.com/api/3/public/futures/candles/mark_price"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T07:30:00.000Z",
      "open": "32414.58",
      "close": "32414.58",
      "min": "32414.58",
      "max": "32414.58"
    },
    {
      "timestamp": "2021-07-07T18:00:00.000Z",
      "open": "34748.31",
      "close": "34748.31",
      "min": "34748.31",
      "max": "34748.31"
    },
    {
      "timestamp": "2021-07-07T12:30:00.000Z",
      "open": "34777.96",
      "close": "34777.96",
      "min": "34777.96",
      "max": "34777.96"
    }
  ]
}

GET /api/3/public/futures/candles/mark_price

Returns mark price candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Limit to candles.
Default value: 10
Maximum value: 1000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open mark price.
close Number Closing mark price.
min Number The lowest mark price for the period.
max Number The highest mark price for the period.

Get Mark Price Candles by Contract

curl "https://api.hitbtc.com/api/3/public/futures/candles/mark_price/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T07:30:00.000Z",
    "open": "32414.58",
    "close": "32414.58",
    "min": "32414.58",
    "max": "32414.58"
  },
  {
    "timestamp": "2021-07-07T18:00:00.000Z",
    "open": "34748.31",
    "close": "34748.31",
    "min": "34748.31",
    "max": "34748.31"
  },
  {
    "timestamp": "2021-07-07T12:30:00.000Z",
    "open": "34777.96",
    "close": "34777.96",
    "min": "34777.96",
    "max": "34777.96"
  }
]

GET /api/3/public/futures/candles/mark_price/{symbol}

Returns mark price candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open mark price.
close Number Closing mark price.
min Number The lowest mark price for the period.
max Number The highest mark price for the period.

Futures Premium Index Candles

Get Premium Index Candles

curl "https://api.hitbtc.com/api/3/public/futures/candles/premium_index"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-08T23:00:00.000Z",
      "open": "0.0001",
      "close": "-0.000204666639856002",
      "min": "-0.000390287528832163",
      "max": "0.000191382142641392"
    },
    {
      "timestamp": "2021-07-08T22:30:00.000Z",
      "open": "-0.000057633026633848",
      "close": "0.00006436921844495",
      "min": "-0.00060179788527768",
      "max": "0.0001"
    },
    {
      "timestamp": "2021-07-08T22:00:00.000Z",
      "open": "0.0001",
      "close": "-0.000205510656144068",
      "min": "-0.000604732863348008",
      "max": "0.0001"
    }
  ]
}

GET /api/3/public/futures/candles/premium_index

Returns premium index candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of contract codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open premium index.
close Number Closing premium index.
min Number The lowest premium index for the period.
max Number The highest premium index for the period.

Get Premium Index Candles by Contract

curl "https://api.hitbtc.com/api/3/public/futures/candles/premium_index/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-08T23:00:00.000Z",
    "open": "0.0001",
    "close": "-0.000204666639856002",
    "min": "-0.000390287528832163",
    "max": "0.000191382142641392"
  },
  {
    "timestamp": "2021-07-08T22:30:00.000Z",
    "open": "-0.000057633026633848",
    "close": "0.00006436921844495",
    "min": "-0.00060179788527768",
    "max": "0.0001"
  },
  {
    "timestamp": "2021-07-08T22:00:00.000Z",
    "open": "0.0001",
    "close": "-0.000205510656144068",
    "min": "-0.000604732863348008",
    "max": "0.0001"
  }
]

GET /api/3/public/futures/candles/premium_index/{symbol}

Returns premium index candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Open premium index.
close Number Closing premium index.
min Number The lowest premium index for the period.
max Number The highest premium index for the period.

Futures Open Interest Candles

Get Open Interest Candles

curl "https://api.hitbtc.com/api/3/public/futures/candles/open_interest"

Response:

{
  "BTCUSDT_PERP": [
    {
      "timestamp": "2021-07-22T16:30:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    },
    {
      "timestamp": "2021-07-22T16:00:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    },
    {
      "timestamp": "2021-07-22T15:30:00.000Z",
      "open": "1.06523",
      "close": "1.06523",
      "min": "1.06523",
      "max": "1.06523"
    }
  ]
}

GET /api/3/public/futures/candles/open_interest

Returns open interest candles for all contracts.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
symbols String Comma-separated list of contract codes.
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 10
Accepted values: 11000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Opening value.
close Number Closing value.
min Number The lowest open interest for the period.
max Number The highest open interest for the period.

Get Open Interest Candles by Contract

curl "https://api.hitbtc.com/api/3/public/futures/candles/open_interest/BTCUSDT_PERP"

Response:

[
  {
    "timestamp": "2021-07-22T16:30:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  },
  {
    "timestamp": "2021-07-22T16:00:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  },
  {
    "timestamp": "2021-07-22T15:30:00.000Z",
    "open": "1.06523",
    "close": "1.06523",
    "min": "1.06523",
    "max": "1.06523"
  }
]

GET /api/3/public/futures/candles/open_interest/{symbol}

Returns open interest candles for a certain contract.

Requires no API key Access Rights.

All parameters are optional.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: ASC, DESC
Default value: DESC
period String Accepted values: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)
Default value: M30 (30 minutes)
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Accepted values: 11000
offset Number Default value: 0
Accepted values: 0100000

Response:

Name Type Description
timestamp DateTime Candle timestamp.
open Number Opening value.
close Number Closing value.
min Number The lowest open interest for the period.
max Number The highest open interest for the period.

Authentication

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

You should create API keys on the API Settings page. You can create multiple API keys with different access rights for your applications.

Alternatively, you may obtain API keys via the Auth API by creating a session (POST /account/auth) and an API key (POST /api-key).

Basic

curl -u "apiKey:secretKey" "https://api.hitbtc.com/api/3/wallet/balance"
import requests

session = requests.session()
session.auth = ("apiKey", "secretKey")
const fetch = require('node-fetch');
const credentials = Buffer
  .from(
    'apiKey'
    + ':'
    + 'secretKey'
  )
  .toString('base64');

fetch(
  'https://api.hitbtc.com/api/3/wallet/balance',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Basic ' + credentials
    }
  }
);

To authorize, place credentials to the request header. Those must be constituted of apiKey and secretKey as follows: "Basic " + apiKey + ":" + secretKey.

HS256

from base64 import b64encode
from hashlib import sha256
from hmac import HMAC
from time import time
from urllib.parse import urlsplit
from requests import Session
from requests.auth import AuthBase


class HS256(AuthBase):
    def __init__(self, api_key: str, secret_key: str, window: int = None):
        self.api_key = api_key
        self.secret_key = secret_key
        self.window = window

    def __call__(self, r):
        url = urlsplit(r.url)
        message = [r.method, url.path]
        if url.query:
            message.append('?')
            message.append(url.query)
        if r.body:
            message.append(r.body)

        timestamp = str(int(time() * 1000))
        window = str(self.window) if self.window else None
        message.append(timestamp)
        if window:
            message.append(window)

        signature = HMAC(key=self.secret_key.encode(),
                         msg=''.join(message).encode(),
                         digestmod=sha256).hexdigest()
        data = [self.api_key, signature, timestamp]
        if window:
            data.append(window)

        base64_encoded = b64encode(':'.join(data).encode()).decode()
        r.headers['Authorization'] = f'HS256 {base64_encoded}'
        return r


auth = HS256(api_key='apiKey', secret_key='secretKey')

with Session() as s:
    response = s.get('https://api.hitbtc.com/api/3/wallet/balance', auth=auth)
    print(response.json())

The alternative authentication method is the HMAC signature.

To send a request, you should establish a persistent session using the credentials signed as follows:

  1. Create an HMAC signature with secret_key as the secret key, SHA256 as the hash algorithm, and payload as the message, structured like:
    <method> + <URL path> + [“?” + <query>] + [<body>] + <timestamp> + [<window>]
  2. Add the authorization header to a request. It should have the following structure:
    "HS256 " + Base64(api_key + ":" + <HMAC signature> + ":" + timestamp + [":" + window])

Spot Trading

Order Model

{
  "id": 828680665,
  "client_order_id": "f4307c6e507e49019907c917b6d7a084",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "13.942",
  "price": "0.011384",
  "quantity_cumulative": "5.240",
  "created_at": "2024-04-16T14:18:47.321Z",
  "updated_at": "2024-04-16T14:18:47.321Z",
  "post_only": false,
  "display_quantity": "0",
  "trades": [
    {
      "id": 1361171432,
      "quantity": "5.240",
      "price": "0.011384",
      "fee": "0.001237803000",
      "taker": true,
      "timestamp": "2024-04-16T14:18:47.321Z"
    }
  ]
}

Order model consists of:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
order_list_id String Optional. Order list identifier. Returned only for an order list request.
contingency_type String Optional. Order list type. Returned only for an order list request.
Possible values:
allOrNone, oneCancelOther, oneTriggerOther, oneTriggerOneCancelOther
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
price Number Optional. Order price.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Optional. Date of order expiration. Specified if time_in_force is GTD.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
original_client_order_id String Optional. Identifier of replaced order.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
trades []Trade Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name Type Description
id Number Trade identifier.
quantity Number Quantity of trade.
price Number Trade price.
fee Number Fee paid for trade.
taker Boolean Liquidity indicator.
timestamp DateTime Date of trade.

Get Spot Trading Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/balance"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/spot/balance').json()

print(b)

Response. All currencies:

[
  {
    "currency": "ETH",
    "available": "10.000000000",
    "reserved": "0.56",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  {
    "currency": "BTC",
    "available": "0.010205869",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  }
]

Response. One currency:

{
  "available": "10.000000000",
  "reserved": "0.56",
  "reserved_margin": "0",
  "cross_margin_reserved": "0"
}

GET /api/3/spot/balance GET /api/3/spot/balance/{currency}

Returns the user's trading balance.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
currency String Optional. Currency filter.

Response:

Name Type Description
currency String Currency code.
available Number Amount available for trading or transfer to wallet.
reserved_margin Number Amount reserved for margin trading.
cross_margin_reserved Number Amount reserved for margin trading funded by a cross–margin account.
reserved Number Total amount reserved for active orders and incomplete transfers to wallet.

Get All Active Spot Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/spot/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "created_at": "2024-04-12T17:17:57.437Z",
    "updated_at": "2024-04-12T17:18:08.610Z"
  }
]

GET /api/3/spot/order

Returns a list of all active spot orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Parameter to filter active spot orders by symbol.

Response: array of spot orders

Get Active Spot Order

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/c1837634ef81472a9cd13c81e7b91401"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/spot/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "created_at": "2024-04-12T17:17:57.437Z",
  "updated_at": "2024-04-12T17:18:08.610Z"
}

GET /api/3/spot/order/{client_order_id}

Returns an active spot order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response: spot order

Create New Spot Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order" \
  -d "symbol=ETHBTC&side=sell&quantity=0.063&price=0.046016"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }

r = session.post('https://api.hitbtc.com/api/3/spot/order/', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

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

POST /api/3/spot/order

Creates a new spot order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Optional. If omitted, an order will be created, and it will be generated by the Server. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
Must be from 8 to 32 long. May include Latin letters of any case, digits, and _, -.
If specified and corresponds to an existing order, a request will be rejected.
symbol String Symbol code.
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Must be set to market, stopMarket, or takeProfitMarket if price was left unspecified.
Accepted values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
Default value: limit
time_in_force String Optional. Time in Force instruction.
Accepted values: GTC, IOC, FOK, Day, GTD
Default value:
FOKtype is market, stopMarket, takeProfitMarket;
GTCtype is limit, stopLimit, takeProfitLimit.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
take_rate Number Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
make_rate Number Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Response: spot order

Price accuracy and quantity

Symbol config contains the tick_size parameter which means that price should be divided by tick_size with no remainder.
quantity should be divided by quantity_increment with no remainder.
By default, if strict_validate is not enabled, the Server rounds half down the price and quantity for tick_size and quantity_increment.

Example of ETHBTC: if tick_size is 0.000001, then price 0.046016 is valid, and 0.0460165 is invalid.

Fees

Charged fee is determined by the symbol's fee_currency. Maker-taker fees offer a transaction rebate make_rate to those who provide liquidity (a maker), while charging customers who take that liquidity take_rate (a taker).

To create buy orders, you must have sufficient balance including fees.

To create market buy orders, you must have sufficient balance including fees.

Available balance > price × quantity + price × quantity × max(take_rate, make_rate)

Order result status

For orders with time_in_force equal to IOC or FOK, the REST API returns final order status: filled or expired.

If an order can be instantly executed, then the REST API returns a status of filled or partiallyFilled in the order's info.

Create New Spot Order List

AON request:

curl \
  -X POST \
  -H 'Content-Type: application/json'\
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/list" \
  -d '{
        "contingency_type": "allOrNone",
        "orders": [
          {
            "symbol": "ETHBTC",
            "side": "sell",
            "quantity": "0.063",
            "type": "market",
            "time_in_force": "FOK"
          },
          {
            "symbol": "BTCUSDT",
            "side": "sell",
            "quantity": "0.057",
            "type": "market",
            "time_in_force": "FOK"
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "allOrNone", "orders": [{"symbol": "ETHBTC", "side": "sell", "quantity": "0.063", "type": "market", "time_in_force": "FOK"}, {"symbol": "BTCUSDT", "side": "sell", "quantity": "0.057", "type": "market", "time_in_force": "FOK"}]}'

r = session.post('https://api.hitbtc.com/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

AON response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "filled",
    "type": "market",
    "time_in_force": "FOK",
    "quantity": "0.063",
    "price": "0.071476",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "allOrNone",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "market",
    "time_in_force": "FOK",
    "quantity": "0.057",
    "price": "43510.67",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "allOrNone",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false
          },
          {
            "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.050000",
            "post_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/spot/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

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

POST /api/3/spot/order/list

Creates a new spot order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
order_list_id String Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to client_order_id of the first order in the request.
contingency_type String Order list type.
Accepted values:
allOrNone (AON) — all orders in the set should be executed within a single transaction or become expired otherwise;
oneCancelOther (OCO) — all orders in the set should be canceled if one of them was executed;
oneTriggerOther (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other;
oneTriggerOneCancelOther (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
orders []Order Orders in the list. There must be 2 or 3 orders for allOrNone/oneCancelOther/oneTriggerOther and 3 — for oneTriggerOneCancelOther. Placing any other number of orders will result in an error.

Order model consists of:

Name Type Description
client_order_id String Optional. Must be different from the identifiers of other orders in the list.
If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
For a allOrNone order list, symbol code must be unique for each order in the list.
For an oneTriggerOneCancelOther order list, symbol code must be the same for all orders in the list (placing orders in different order books is not supported).
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Accepted values:
for allOrNonelimit, market;
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — limit, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket;
for oneTriggerOneCancelOtherlimit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
Default value: limit
time_in_force String Optional (required for allOrNone). Time in Force instruction.
Accepted values:
for allOrNoneFOK;
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — GTC, IOC (except limit orders), FOK (except limit orders), Day, GTD;
for oneTriggerOneCancelOtherGTC, IOC, FOK, Day, GTD.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is '0').
take_rate Number Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
make_rate Number Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Response: array of spot orders

Replace Spot Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175'}

r = session.patch('https://api.hitbtc.com/api/3/spot/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

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

PATCH /api/3/spot/order/{client_order_id}

Replaces a spot order

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
new_client_order_id String Optional. client_order_id for a new order.
quantity Number Order quantity.
price Number Optional. Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
strict_validate Boolean Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.

Response: spot order

Cancel All Spot Orders

DELETE /api/3/spot/order

Cancels all active spot orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Parameter to filter active spot orders by symbol.

Response: array of spot orders

Cancel Spot Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/spot/order/{client_order_id}

Cancels a spot order.

Requires the "Place/cancel orders" API key Access Right.

Response: spot order

Get All Trading Commissions

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/fee"

Response:

[
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
]

GET /api/3/spot/fee

Returns personal trading commission rates for all symbols.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Trading Commission

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/fee/ETHBTC"

Response:

{
  "symbol": "ETHBTC",
  "take_rate": "0.001",
  "make_rate": "-0.0001"
}

GET /api/3/spot/fee/{symbol}

Returns personal trading commission rate by symbol.

Requires the "Place/cancel orders" API key Access Right.

Spot Trading History

Spot Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/history/order?symbol=ETHBTC"
[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/spot/history/order

Returns all spot orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
client_order_id String If specified, other parameters will be ignored, including limit and offset.
symbol String Comma-separated symbol codes.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
by String Filter type.
Accepted values: timestamp, id
Default value: id
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
display_quantity String The visible part of the hidden order quantity.
price Number Order price.
price_average Number Average price of executed order quantity.
expire_time DateTime Date of order expiration. Specified if time_in_force is GTD.
stop_price Number The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
order_list_id String Optional. Order list identifier.
contingency_type String Optional. Order list type.
Possible values:
allOrNone, oneCancelOther, oneTriggerOther, oneTriggerOneCancelOther

Spot Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/spot/history/trade?symbol=ETHBTC"
[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "taker": true
  }
]

GET /api/3/spot/history/trade

Returns the user's spot trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
order_id String Unique order identifier as assigned by exchange.
symbol String Comma-separated symbol codes.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
by String Filter type.
Accepted values: timestamp, id
Default value: id
from DateTime or Number Interval initial value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
till DateTime or Number Interval end value.
If sorting by timestamp is used, then DateTime; otherwise — Number.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id Number Trade unique identifier as assigned by exchange.
order_id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
quantity Number Trade quantity.
price Number Trade price.
fee Number Trade commission.
Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
timestamp DateTime Trade timestamp.
taker Boolean Liquidity indicator.

Margin Trading

Learn how margin trading works at our support center https://support.hitbtc.com/en/support/solutions/articles/63000225029-what-is-margin-trading

Margin Order Model

Margin Order:

{
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-16T14:18:47.321Z",
    "post_only": false,
    "display_quantity": "0",
    "margin_mode": "isolated",
    "trades": [
      {
        "id": 1361171432,
        "position_id": 123,
        "quantity": "5.240",
        "price": "0.011384",
        "fee": "0.001237803000",
        "taker": true,
        "timestamp": "2024-04-16T14:18:47.321Z"
      }
    ]
  }
}

Margin order model consists of:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
order_list_id String Optional. Order list identifier.
contingency_type String Optional. Order list type.
Possible values:
allOrNone, oneCancelOther, oneTriggerOther, oneTriggerOneCancelOther
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
price Number Optional. Order price.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Optional. Date of order expiration. Specified if time_in_force is GTD.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
original_client_order_id String Optional. Identifier of replaced order.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
margin_mode String Margin mode.
Possible values: isolated, cross
trades []Trade Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name Type Description
id Number Trade identifier.
quantity Number Quantity of trade.
price Number Trade price.
fee Number Fee paid for trade.
position_id Number Position identifier of the trade.
taker Boolean Liquidity indicator.
timestamp DateTime Date of trade.

Margin Account Model

Margin Account:

[
  {
    "symbol": "ETHUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  },
  {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2024-04-19T17:26:10.758Z",
    "updated_at": "2021-07-01T21:20:03.64Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.097289003250",
        "reserved_orders": "0",
        "reserved_positions": "0.029557397625"
      }
    ],
    "positions": [
      {
        "id": 475421,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33304.11",
        "price_margin_call": "25395.20",
        "price_liquidation": "24884.62",
        "pnl": "0",
        "created_at": "2024-04-19T17:26:10.758Z",
        "updated_at": "2021-07-01T21:20:03.64Z"
      }
    ]
  }
]

Margin Account model consists of:

Name Type Description
symbol String Symbol code.
leverage Number Optional. The ratio of borrowed funds to trader's initial margin.
type String Type of margin.
Possible values: isolated, cross
created_at DateTime Date of account creation.
updated_at DateTime Date of account last update.
currencies []Currency Amount of funds on Margin Account.
positions []Position Optional. Open positions of the Margin Account.

Currency Model

{
  "code": "USDT",
  "margin_balance": "999.9841334080000",
  "reserved_orders": "0",
  "reserved_positions": "1.605699104000"
}

Currency model consists of:

Name Type Description
code String Currency code.
margin_balance Number The total value of funds reserved for the position.
reserved_orders Number The value reserved for active orders in the position.
reserved_positions Number The minimum value reserved for position's executed quantity that cannot be reduced.

Position Model

{
  "id": 298724,
  "symbol": "BTCUSDT",
  "quantity": "-0.00100",
  "margin_mode": "isolated",
  "pnl": "0",
  "price_entry": "7933.30",
  "price_margin_call": "887772.25",
  "price_liquidation": "914625.61",
  "created_at": "2024-04-21T14:33:34.723Z",
  "updated_at": "2024-04-21T14:33:46.149Z"
}

Position model consists of:

Name Type Description
id String Position identifier.
symbol String Symbol code.
quantity Number Position quantity.
leverage Number Optional. The ratio of borrowed funds to trader's initial margin.
margin_mode String Margin mode.
Possible values: isolated, cross
pnl Number Unrealized profit and loss.
fee_cumulative String Total amount of fees paid throughout the position lifetime until it is closed.
This value does zero out after the position closes and does not when it flips.
price_entry Number Average weighted price of position open orders.
price_margin_call Number The mark price of margin call.
price_liquidation Number The mark price of force close.
created_at DateTime Position creation date and time.
updated_at DateTime Position last update date and time.

Get All Margin Accounts

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/account"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/margin/account').json()

print(b)

Response:

[
  {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-01T23:24:46.27Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080816916750",
        "reserved_orders": "0.000018250000",
        "reserved_positions": "0.333861705262"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27259.95",
        "price_liquidation": "26711.87",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-01T23:24:46.27Z"
      }
    ]
  },
  {
    "symbol": "ETHUSDT",
    "type": "cross",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  }
]

GET /api/3/margin/account

Returns the user's all Margin Accounts' details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Isolated Margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/account/isolated/BTCUSDT"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/margin/account/isolated/BTCUSDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT",
  "type": "isolated",
  "leverage": "12.00",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/margin/account/isolated/{symbol}

Returns an isolated margin account details by symbol.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Cross–margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/account/cross/USDT"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/margin/account/cross/USDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT",
  "type": "cross",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "leverage": "12.00",
      "margin_mode": "cross",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/margin/account/cross/{currency}

Returns a cross-margin account details by currency.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/account/isolated/BTCUSDT" \
  -d "margin_balance=123.44"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.put('https://api.hitbtc.com/api/3/margin/account/isolated/BTCUSDT', json={"margin_balance":"123.4455", "strict_validate": True}).json()

print(b)
{
  "symbol": "BTCUSDT",
  "type": "isolated",
  "leverage": "12.00",
  "created_at": "2024-04-19T17:26:10.758Z",
  "updated_at": "2021-07-01T21:20:03.64Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.097289003250",
      "reserved_orders": "0",
      "reserved_positions": "0.029557397625"
    }
  ],
  "positions": [
    {
      "id": 475421,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "price_entry": "33304.11",
      "price_margin_call": "25395.20",
      "price_liquidation": "24884.62",
      "pnl": "0",
      "created_at": "2024-04-19T17:26:10.758Z",
      "updated_at": "2021-07-01T21:20:03.64Z"
    }
  ]
}

PUT /api/3/margin/account/{margin_mode}/{instrument}

Creates or updates an isolated margin account or a cross–margin account.

Setting the margin balance to zero will lead to closing a margin account and retrieval of all formerly reserved funds to the trading account.

To withdraw all funds from the margin account send a request with margin_balance equal to "0".

Returns the created/updated Margin Account details.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
margin_mode String Margin mode.
Accepted values: isolated, cross
instrument String Symbol or currency code for an isolated and a cross-margin position respectively.
margin_balance Number Amount of currency. "0" to close the margin account.
strict_validate Boolean The value indicating whether the margin_balance is going to be checked for correct non-exponential format and currency precision.

Close Margin Positions

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/position"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.hitbtc.com/api/3/margin/position').json()

print(b)

DELETE /api/3/margin/position

Closes all open positions.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Close Margin Position

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/position/isolated/BTCUSDT"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.hitbtc.com/api/3/margin/position/isolated/BTCUSDT', json={"price": "9800.50", "strict_validate": True}).json()

print(b)

DELETE /api/3/margin/position/{margin_mode}/{symbol}

Closes open positions by symbol.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Symbol code.
margin_mode String Margin mode.
Accepted values: isolated, cross
price Number Optional. If a price is defined, then close order would be a limit order, instead, close order would be a market order.
strict_validate Boolean Optional.
The value indicating whether the price is going to be checked for incrementation within the symbol’s tick size step. See the symbol's tick_size.
Default value: false

Get Active Margin Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/margin/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "reduce_only": false,
    "margin_mode": "isolated",
    "created_at": "2024-04-12T17:17:57.437Z",
    "updated_at": "2024-04-12T17:18:08.610Z"
  }
]

GET /api/3/margin/order

Returns an array of active margin orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Parameter to filter active orders by symbol.

Get Active Margin Order

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/c1837634ef81472a9cd13c81e7b91401"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/margin/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T17:17:57.437Z",
  "updated_at": "2024-04-12T17:18:08.610Z"
}

GET /api/3/margin/order/{client_order_id}

Returns an active margin order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create Margin Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order" \
  -d "symbol=ETHBTC&side=sell&quantity=0.063&price=0.046016"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016'}

r = session.post('https://api.hitbtc.com/api/3/margin/order', data = orderData)

print(r.json())

Response:

{
  "id": 583463871253,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

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

POST /api/3/margin/order

Requires the Margin Account for the order symbol.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Optional. If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Trading symbol.
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Must be set to market, stopMarket, or takeProfitMarket if price was left unspecified.
Accepted values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
Default value: limit
time_in_force String Optional. Time in Force instruction.
Accepted values: GTC, IOC, FOK, Day, GTD
Default value:
FOKtype is market, stopMarket, takeProfitMarket;
GTCtype is limit, stopLimit, takeProfitLimit.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated

Response: order

Create New Margin Order List

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "symbol": "ETHBTC",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "symbol": "ETHBTC",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"symbol": "ETHBTC", "side": "buy", "type": "limit","time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
            {
                "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
                "symbol": "ETHBTC",
                "side": "buy",
                "type": "limit",
                "time_in_force": "GTC",
                "quantity": "0.063",
                "price": "0.046016",
                "post_only": false,
                "reduce_only": false
            },
            {
                "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
                "symbol": "ETHBTC",
                "side": "sell",
                "type": "stopMarket",
                "time_in_force": "GTC",
                "quantity": "0.063",
                "stop_price": "0.044050",
                "post_only": false,
                "reduce_only": false
            }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
            {
              "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
              "symbol": "ETHBTC",
              "side": "buy",
              "type": "limit",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "price": "0.046016",
              "post_only": false,
              "reduce_only": false
            },
            {
              "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", \
              "symbol": "ETHBTC",
              "side": "sell",
              "type": "limit",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "price": "0.050000",
              "post_only": false,
              "reduce_only": false
            },
            {
              "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
              "symbol": "ETHBTC",
              "side": "sell",
              "type": "stopMarket",
              "time_in_force": "GTC",
              "quantity": "0.063",
              "stop_price": "0.044050",
              "post_only": false,
              "reduce_only": false
            }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/margin/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

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

POST /api/3/margin/order/list

Creates a new margin order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
order_list_id String Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to client_order_id of the first order in the request.
contingency_type String Order list type.
Accepted values:
oneCancelOther (OCO) — all orders in the set should be canceled if one of them was executed;
oneTriggerOther (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other;
oneTriggerOneCancelOther (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
orders []Order Orders in the list. There must be 2 or 3 orders for allOrNone/oneCancelOther/oneTriggerOther and 3 — for oneTriggerOneCancelOther. Placing any other number of orders will result in an error.

Order model consists of:

Name Type Description
client_order_id String Optional. Must be different from the identifiers of other orders in the list.
If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
Must be the same for all orders in an oneTriggerOneCancelOther order list (placing orders in different order books is not supported).
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — limit, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket;
for oneTriggerOneCancelOtherlimit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
Default value: limit
time_in_force String Optional. Time in Force instruction.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — GTC, IOC (except limit orders), FOK (except limit orders), Day, GTD;
for oneTriggerOneCancelOtherGTC, IOC, FOK, Day, GTD.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is '0').
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated

Response: array of margin orders

Replace Margin Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175' }

r = session.patch('https://api.hitbtc.com/api/3/margin/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

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

PATCH /api/3/margin/order/{client_order_id}

Replaces a margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
new_client_order_id String Optional. client_order_id for a new order.
quantity Number Order quantity.
price Number Optional. Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
strict_validate Boolean Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.

Response: margin order

Cancel All Margin Orders

DELETE /api/3/margin/order

Cancels all active margin orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Parameter to filter active margin orders by symbol.

Response: array of margin orders

Cancel Margin Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.000",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T18:08:57.226Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/margin/order/{client_order_id}

Cancels a margin order.

Requires the "Place/cancel orders" API key Access Right.

Response: margin order

Get Margin Position Parameters

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/config"

Response:

{
  "config": [
    {
      "symbol": "BTCUSD",
      "margin_call_leverage_mul": "1.50",
      "liquidation_leverage_mul": "2.00",
      "max_initial_leverage": "10.00",
      "margin_mode": "Isolated",
      "force_close_fee": "0.05",
      "enabled": true,
      "active": true,
      "limit_base": "50000.00",
      "limit_power": "2.2",
      "unlimited_threshold": "10.0"
    }
  ]
}

GET /api/3/margin/config

Returns information about margin position configuration.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name Type Description
symbol String Trading symbol.
margin_call_leverage_mul Number Multiplier for calculating margin call leverage.
liquidation_leverage_mul Number Multiplier for calculating liquidation leverage.
max_initial_leverage Number Maximum leverage that the user can use for margin trading.
margin_mode String Mode of margin trading.
Possible values: Isolated, Cross
force_close_fee Number Fee for the force closing of the position.
enabled Boolean Is margin trading available.
active Boolean Are there any positions which comply with the parameters (including not yet opened).
limit_base Number Optional. An absolute maximum that a position value can reach. Returns only if the risk limit exists.
limit_power Number Optional. Power which determines the influence of the leverage on the risk limit value. Returns only if the risk limit exists.
unlimited_threshold Number Optional. Position leverage below which the risk limit is not calculated. Returns only if the risk limit exists.

Margin Trading History

Margin Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/history/order?symbol=ETHBTC"
[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/margin/history/order

Returns all margin orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
client_order_id String If set, other parameters will be ignored, including limit and offset.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
by String Filter type.
Accepted values: timestamp, id
Default value: id
symbol String Comma-separated symbol codes.
from DateTime Interval initial value.
If sorting by timestamp is used, then DateTime; otherwise Number.
till DateTime Interval end value.
If sorting by timestamp is used, then DateTime; otherwise Number.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
display_quantity String The visible part of the hidden order quantity.
price Number Order price.
price_average Number Average price of executed order quantity.
expire_time DateTime Date of order expiration. Specified if time_in_force is GTD.
position_id Number Optional. Position identifier of the order.
stop_price Number The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
order_list_id String Optional. Order list identifier.
contingency_type String Optional. Order list type.
Possible values: oneCancelOther, oneTriggerOther, oneTriggerOneCancelOther
margin_mode String Margin mode.
Possible values: isolated, cross
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.

Margin Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/history/trade?symbol=ETHBTC"
[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  }
]

GET /api/3/margin/history/trade

Get the user's trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
order_id Number Unique order identifier as assigned by exchange.
position_id Number Position identifier of the taker's order in the trade.
symbol String Comma-separated symbol codes.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
by String Filter type.
Accepted values: timestamp, id
Default value: id
from DateTime or Number Interval initial value. If sorting by timestamp is used, then DateTime; otherwise Number.
till DateTime or Number Interval end value. If sorting by timestamp is used, then DateTime; otherwise Number.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id String Trade unique identifier as assigned by exchange.
order_id String Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Trading symbol.
side String Trade side.
Possible values: sell, buy
quantity Number Trade quantity.
price Number Trade price.
fee Number Trade commission.
Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
timestamp DateTime Trade timestamp.
taker Boolean Liquidity indicator.
position_id Number Optional. Position identifier of the taker's order in the trade.
pnl Number Optional. Realized Profit and Loss on this trade.
liquidation Boolean Optional. Whether it is a liquidation trade.
margin_mode String Margin mode.
Possible values: isolated, cross

Margin Positions History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/history/positions"
[
  {
    "id":3001,
    "entry_value": "0",
    "entry_price": "0.000",
    "avg_buy_price": "1978.057",
    "avg_sell_price": "3851.001",
    "quantity": "0",
    "margin_call_price": "0.000",
    "liquidation_price": "0.000",
    "bankruptcy_price": "0.000",
    "margin": "100.169018395350",
    "required_margin": "0",
    "orders_margin": "0.000006557500",
    "pnl": "0.187294400000",
    "leverage": "10.00",
    "margin_mode": "isolated",
    "state": "closed",
    "symbol": "ETHUSDT",
    "margin_call": false,
    "create_timestamp": 1626881592397,
    "update_timestamp": 1639570624225
  }
]

GET /api/3/margin/history/positions

Get the margin positions history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
sort String Optional. Sort direction.
Accepted values: DESC, ASC
Default value: DESC
from Number Optional. Interval initial value in nanoseconds. Minimum value: 1
till Number Optional. Interval end value in nanoseconds. Minimum value: 1
limit Number Optional. Default value: 100
Maximum value: 1000
offset Number Optional. Default value: 0
Maximum value: 100000
by String The name of the field to order the results by (only sorting by update_timestamp is allowed).
Accepted values: ts, timestamp

Response:

Name Type Description
id Number Position identifier.
entry_value String Position value in currency.
entry_price String Weighted average open price.
avg_buy_price String Weighted average buy price.
avg_sell_price String Weighted average sell price.
quantity String Position quantity.
margin_call_price String If the market is equal to or worse than this price, a margin call will be issued.
liquidation_price String The price at which the platform begins to close the position.
bankruptcy_price String The price at which the position can no longer be closed with any non-negative PnL.
margin String Amount of margin expressed in the quote currency.
required_margin String Margin reserved for close orders.
orders_margin String Margin reserved for open orders.
pnl String Unrealized Profit and Loss.
leverage String Position leverage.
margin_mode String Mode of margin trading.
Possible values: isolated, cross
state String Position state.
Possible values: closed, active, liquidated
fee_cumulative String Total amount of fees paid throughout the position lifetime until it is closed.
This value does zero out after the position closes and does not when it flips.
symbol String Symbol code.
margin_call Boolean Flag indicating the position is close to the liquidation, and increased margin may prevent it from happening.
create_timestamp Number Timestamp of position creation in nanoseconds.
update_timestamp Number Timestamp of position update in nanoseconds.

Margin Clearing Details

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/margin/history/clearing"
[
  {
    "timestamp": 1646524800267,
    "position_id": 972,
    "position_quantity": "0.00010",
    "position_entry_value": "5.126379000000",
    "type": "interest",
    "symbol": "BTCUSDT",
    "currency": "USD",
    "amount": "0.011819526000",
    "rate": "0.0001",
    "debt_delta": "0"
  }
]

GET /api/3/margin/history/clearing

Get clearing details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
currency String Quote currency code.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
from Number Interval initial value in nanoseconds. Minimum value: 1
till Number Interval end value in nanoseconds. Minimum value: 1
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
timestamp Number Transfer timestamp in nanoseconds.
position_id Number Optional. Position identifier.
position_quantity Number Optional. Position quantity.
position_entry_value Number Optional. Position value in currency.
type String Transfer type.
Possible values: interest
symbol String Optional. Symbol code.
currency String Transfer currency.
amount Number Transfer amount.
rate Number Optional. Interest rate. It is null if the withdrawal occurred during a close trade (debt collection).
trade_id Number Optional. Trade identifier. Applicable if the withdrawal occurred during a close trade (debt collection).
debt_delta Number Optional. Debt value. Returned if a user was unable to pay interest during the last withdrawal but had a positive UPnL.

Futures Trading

Futures Order Model

Futures Order:

{
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "BTCUSDT_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "quantity_cumulative": "5.240",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-16T14:18:47.321Z",
    "post_only": false,
    "display_quantity": "0",
    "margin_mode": "isolated",
    "trades": [
      {
        "id": 1361171432,
        "position_id": 123,
        "quantity": "5.240",
        "price": "0.011384",
        "fee": "0.001237803000",
        "taker": true,
        "timestamp": "2024-04-16T14:18:47.321Z"
      }
    ]
  }
}

Margin order model consists of:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
order_list_id String Optional. Order list identifier.
contingency_type String Optional. Order list type.
Possible values:
allOrNone, oneCancelOther, oneTriggerOneCancelOther
symbol String Contract code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
price Number Optional. Order price.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Optional. Date of order expiration. Specified if time_in_force is GTD.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
original_client_order_id String Optional. Identifier of replaced order.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
margin_mode String Margin mode.
Possible values: isolated, cross
trades []Trade Optional. List of trades. Never returned for an order list request.

Trade model consists of:

Name Type Description
id Number Trade identifier.
quantity Number Quantity of trade.
price Number Trade price.
fee Number Fee paid for trade.
position_id Number Position identifier of the trade.
taker Boolean Liquidity indicator.
timestamp DateTime Date of trade.

Futures Margin Account Model

Futures Margin Account:

[
  {
    "symbol": "ETHUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:20:25.118Z",
    "updated_at": "2021-07-01T21:20:25.118Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.002000000000",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null
  },
  {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2024-04-19T17:26:10.758Z",
    "updated_at": "2021-07-01T21:20:03.64Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.097289003250",
        "reserved_orders": "0",
        "reserved_positions": "0.029557397625"
      }
    ],
    "positions": [
      {
        "id": 475421,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33304.11",
        "price_margin_call": "25395.20",
        "price_liquidation": "24884.62",
        "pnl": "0",
        "created_at": "2024-04-19T17:26:10.758Z",
        "updated_at": "2021-07-01T21:20:03.64Z"
      }
    ]
  }
]

Margin Account model consists of:

Name Type Description
symbol String Contract code.
leverage Number Optional. The ratio of borrowed funds to trader's initial margin.
type String Type of margin.
Possible values: isolated, cross
created_at DateTime Date of account creation.
updated_at DateTime Date of account last update.
currencies []Currency Amount of funds on Margin Account.
positions []Position Optional. Open positions of the Margin Account.

Currency Model

{
  "code": "USDT",
  "margin_balance": "999.9841334080000",
  "reserved_orders": "0",
  "reserved_positions": "1.605699104000"
}

Currency model consists of:

Name Type Description
code String Currency code.
margin_balance Number The total value of funds reserved for the position.
reserved_orders Number The value reserved for active orders in the position.
reserved_positions Number The minimum value reserved for position's executed quantity that cannot be reduced.

Position Model

{
  "id": 298724,
  "symbol": "BTCUSDT_PERP",
  "quantity": "-0.00100",
  "leverage": "12.00",
  "margin_mode": "isolated",
  "pnl": "0",
  "price_entry": "7933.30",
  "price_margin_call": "887772.25",
  "price_liquidation": "914625.61",
  "created_at": "2024-04-21T14:33:34.723Z",
  "updated_at": "2024-04-21T14:33:46.149Z"
}

Position model consists of:

Name Type Description
id String Position identifier.
symbol String Contract code.
quantity Number Position quantity.
leverage Number The ratio of borrowed funds to trader's initial margin.
margin_mode String Margin mode.
Possible values: isolated, cross
pnl Number Unrealized profit and loss.
fee_cumulative String Total amount of fees paid throughout the position lifetime until it is closed.
This value does zero out after the position closes and does not when it flips.
price_entry Number Average weighted price of position open orders.
price_margin_call Number The mark price of margin call.
price_liquidation Number The mark price of force close.
created_at DateTime Position creation date and time.
updated_at DateTime Position last update date and time.

Get Trading Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/balance"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/balance').json()

print(b)

Response. All currencies:

[
  {
    "currency": "ETH",
    "available": "10.000000000",
    "reserved": "0.56",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  {
    "currency": "BTC",
    "available": "0.010205869",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  }
]

Response. One currency:

{
  "available": "10.000000000",
  "reserved": "0.56",
  "reserved_margin": "0",
  "cross_margin_reserved": "0"
}

GET /api/3/futures/balance GET /api/3/futures/balance/{currency}

Returns the user's trading balance.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
currency String Optional. Currency filter.

Response:

Name Type Description
currency String Currency code.
available Number Amount available for trading or transfer to wallet.
reserved Number Total amount reserved for active orders, incomplete transfers to wallet, and margin trading.
reserved_margin Number Amount reserved for margin trading funded by an isolated margin account.
cross_margin_reserved Number Amount reserved for margin trading funded by a cross–margin account.

Get Futures Margin Accounts

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/account"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/account').json()

print(b)

Response:

[
  {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-01T23:24:46.27Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080816916750",
        "reserved_orders": "0.000018250000",
        "reserved_positions": "0.333861705262"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27259.95",
        "price_liquidation": "26711.87",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-01T23:24:46.27Z"
      }
    ]
  }
]

GET /api/3/futures/account

Returns all user's Futures Margin Accounts.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/account/isolated/BTCUSDT_PERP"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/account/isolated/BTCUSDT_PERP').json()

print(b)

GET /api/3/futures/account/isolated/{symbol}

Returns Futures Margin Account details by symbol.

A full margin model description can be found in the "Margin Account Model" section.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Futures Cross–margin Account

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/account/cross/USDT"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/account/cross/USDT').json()

print(b)

Response:

{
  "symbol": "BTCUSDT_PERP",
  "type": "cross",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080816916750",
      "reserved_orders": "0.000018250000",
      "reserved_positions": "0.333861705262"
    }
  ],
  "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT_PERP",
      "quantity": "0.00001",
      "leverage": "12.00",
      "margin_mode": "cross",
      "price_entry": "33386.18",
      "price_margin_call": "27259.95",
      "price_liquidation": "26711.87",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-01T23:24:46.27Z"
    }
  ]
}

GET /api/3/futures/account/cross/{currency}

Returns a cross-margin account details by currency.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/account/isolated/BTCUSDT_PERP" \
  -d "margin_balance=123.44&leverage=100"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.put('https://api.hitbtc.com/api/3/futures/account/isolated/BTCUSDT_PERP', json={"margin_balance":"123.4455", "leverage": "100", "strict_validate": True}).json()
print(b)

Response:

{
  "symbol": "BTCUSDT_PERP",
  "type": "isolated",
  "leverage": "100.00",
  "created_at": "2021-07-01T21:43:19.727Z",
  "updated_at": "2021-07-01T23:24:46.27Z",
  "currencies": [
  {
    "code": "USDT",
    "margin_balance": "123.4455",
    "reserved_orders": "0",
    "reserved_positions": "0"
  }
  ],
  "positions": null
}

PUT /api/3/futures/account/{margin_mode}/{symbol}

Creates or updates a margin account. Setting margin balance to zero will lead to closing the margin account and retrieval all formerly reserved funds to the trading account.

Returns margin account details.

To withdraw all funds from the margin account send a request with margin_balance equal to "0".

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
margin_mode String Margin mode.
Accepted values: isolated, cross
margin_balance Number Amount of currency reserved.
leverage Number Optional. User leverage.
Required if the balance of the isolated margin account is equal to zero.
Minimum value: "1"
Maximum value: "1000"
strict_validate Boolean Optional. The value indicating whether the margin_balance is going to be checked for correct non-exponential format and currency precision.

Close All Futures Margin Positions

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/position"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.hitbtc.com/api/3/futures/position').json()

print(b)

DELETE /api/3/futures/position

Closes all open positions.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Close Futures Margin Position

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/position/isolated/BTCUSDT_PERP"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.delete('https://api.hitbtc.com/api/3/futures/position/isolated/BTCUSDT_PERP', json={"price": "9800.50", "strict_validate": True}).json()
print(b)

DELETE /api/3/futures/position/{margin_mode}/{symbol}

Closes open position by contract.

Returns a list of the successfully closed margin positions.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Contract code.
margin_mode String Margin mode.
Accepted values: isolated, cross
price Number Optional. If a price is defined, then close order would be a limit order with the specified price, instead, close order would be a market order with the market price.
strict_validate Boolean Optional. The value indicating whether the price is going to be checked for incrementation within the symbol’s tick size step. See the symbol's tick_size.
Default value: false

Get Active Futures Orders

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/order').json()

print(b)

Response:

[
  {
    "id": 840450210,
    "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.020",
    "price": "0.046001",
    "quantity_cumulative": "0.005",
    "post_only": false,
    "reduce_only": false,
    "margin_mode": "isolated",
    "created_at": "2024-04-12T16:16:30.430Z",
    "updated_at": "2024-04-12T16:17:15.620Z"
  }
]

GET /api/3/futures/order

Returns an array of active futures orders.

A full order description can be found in the "Margin Order Model" section.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Contract code.

Response: array of orders

Get Active Futures Order

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/c1837634ef81472a9cd13c81e7b91401"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")

b = session.get('https://api.hitbtc.com/api/3/futures/order/c1837634ef81472a9cd13c81e7b91401').json()

print(b)

Response:

{
  "id": 840450210,
  "client_order_id": "c1837634ef81472a9cd13c81e7b91401",
  "symbol": "ETHBTC_PERP",
  "side": "buy",
  "status": "partiallyFilled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.020",
  "price": "0.046001",
  "quantity_cumulative": "0.005",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T16:16:30.430Z",
  "updated_at": "2024-04-12T16:17:15.620Z"
}

GET /api/3/futures/order/{client_order_id}

Returns an active order by client_order_id.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create Futures Order

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order" \
  -d "symbol=ETHBTC_PERP&side=sell&quantity=0.063&price=0.046016"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'symbol':'ETHBTC_PERP', 'side': 'sell', 'quantity': '0.063', 'price': '0.046016' }

r = session.post('https://api.hitbtc.com/api/3/futures/order', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T17:01:05.092Z"
}

Error response example:

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

POST /api/3/futures/order

Creates a new futures order.

A full order description can be found in the "Margin Order Model" subsection.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Optional. If omitted, an order will be created, and it will be generated by the Server. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
Must be from 8 to 32 characters long. May include Latin letters of any case, digits, and _, -.
If specified and corresponds to an existing order, a request will be rejected.
symbol String Contract code.
side String Trade side.
Possible values: sell, buy
type String Optional. Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
Default value: limit
time_in_force String Optional. Time in Force instruction.
Possible values: GTC, IOC, FOK, Day, GTD
Default value:
FOKtype is market, stopMarket, takeProfitMarket;
GTCtype is limit, stopLimit, takeProfitLimit.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.

Response: futures order

Create New Futures Order List

OCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/list" \
  -d '{
        "contingency_type": "oneCancelOther",
        "orders": [
          {
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneCancelOther", "orders": [{"symbol": "ETHBTC_PERP", "side": "buy", "type": "limit","time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/list" \
  -d '{
        "contingency_type": "oneTriggerOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC_PERP", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OTO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.063",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.044016",
    "quantity_cumulative": "0.057",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

OTOCO request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/list" \
  -d '{
        "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
        "contingency_type": "oneTriggerOneCancelOther",
        "orders": [
          {
            "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
            "symbol": "ETHBTC_PERP",
            "side": "buy",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.046016",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "limit",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "price": "0.050000",
            "post_only": false,
            "reduce_only": false
          },
          {
            "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
            "symbol": "ETHBTC_PERP",
            "side": "sell",
            "type": "stopMarket",
            "time_in_force": "GTC",
            "quantity": "0.063",
            "stop_price": "0.044050",
            "post_only": false,
            "reduce_only": false
          }
        ]
      }'
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
headers = {'Content-Type': 'application/json'}
orderData = '{"contingency_type": "oneTriggerOneCancelOther", "orders": [{"client_order_id": "d8574207d9e3b16a4a5511753eeef175", "symbol": "ETHBTC_PERP", "side": "buy", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.046016", "post_only": false, "reduce_only": false}, {"client_order_id": "2723cdfba2d609b621d5d055e3ef9be2", "symbol": "ETHBTC_PERP", "side": "sell", "type": "limit", "time_in_force": "GTC", "quantity": "0.063", "price": "0.050000", "post_only": false, "reduce_only": false}, {"client_order_id": "a53406ea49e160c63b620ca21e9fb634", "symbol": "ETHBTC_PERP", "side": "sell", "type": "stopMarket", "time_in_force": "GTC", "quantity": "0.063", "stop_price": "0.044050", "post_only": false, "reduce_only": false}]}'

r = session.post('https://api.hitbtc.com/api/3/futures/order/list', data = orderData, headers=headers)

print(r.json())

OTOCO response:

[
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "2723cdfba2d609b621d5d055e3ef9be2",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.050000",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "inactive": true,
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneTriggerOneCancelOther",
    "margin_mode": "isolated",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  }
]

Error response example:

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

POST /api/3/futures/order/list

Creates a new futures order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
order_list_id String Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to client_order_id of the first order in the request.
contingency_type String Order list type.
Accepted values:
oneCancelOther (OCO) — all orders in the set should be canceled if one of them was executed;
oneTriggerOther (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other;
oneTriggerOneCancelOther (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
orders []Order Orders in the list. There must be 2 or 3 orders for allOrNone/oneCancelOther/oneTriggerOther and 3 — for oneTriggerOneCancelOther. Placing any other number of orders will result in an error.

Order model consists of:

Name Type Description
client_order_id String Optional. Must be different from the identifiers of other orders in the list.
If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
Must be the same for all orders in an oneTriggerOneCancelOther order list (placing orders in different order books is not supported).
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — limit, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket;
for oneTriggerOneCancelOtherlimit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
Default value: limit
time_in_force String Optional. Time in Force instruction.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — GTC, IOC (except limit orders), FOK (except limit orders), Day, GTD;
for oneTriggerOneCancelOtherGTC, IOC, FOK, Day, GTD.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is '0').
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.

Response: array of futures orders

Cancel Futures Orders

DELETE /api/3/futures/order

Cancels all active futures orders or all active futures orders for the specified contract.

Returns a list of canceled futures orders.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Optional. Parameter to filter active futures orders by contract code.

Replace Futures Order

curl \
  -X PATCH \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/d8574207d9e3b16a4a5511753eeef174" \
  -d "quantity=0.063&price=0.046016&new_client_order_id=d8574207d9e3b16a4a5511753eeef175"
import requests


session = requests.session()
session.auth = ("apiKey", "secretKey")
orderData = {'quantity': '0.063', 'price': '0.046016', 'new_client_order_id': 'd8574207d9e3b16a4a5511753eeef175'}

r = session.patch('https://api.hitbtc.com/api/3/futures/order/d8574207d9e3b16a4a5511753eeef174', data = orderData)

print(r.json())

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "new",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.063",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-12T16:16:30.430Z",
  "updated_at": "2024-04-12T16:17:15.620Z"
}

Error response example:

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

PATCH /api/3/futures/order/{client_order_id}

Replaces a futures order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
new_client_order_id String Optional. Unique order identifier given by the trader or the system.
quantity Number Order quantity.
price Number Optional. Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
strict_validate Boolean Optional. Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.

Response: futures order

Cancel Futures Order

curl \
  -X DELETE \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/order/d8574207d9e3b16a4a5511753eeef175"

Response:

{
  "id": 0,
  "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
  "symbol": "ETHBTC_PERP",
  "side": "sell",
  "status": "canceled",
  "type": "limit",
  "time_in_force": "GTC",
  "quantity": "0.000",
  "price": "0.046016",
  "quantity_cumulative": "0.000",
  "post_only": false,
  "reduce_only": false,
  "margin_mode": "isolated",
  "created_at": "2024-04-15T17:01:05.092Z",
  "updated_at": "2024-04-15T18:08:57.226Z"
}

Example of Order not found error response:

{
  "error": {
    "code": 20002,
    "message": "Order not found",
    "description": ""
  }
}

DELETE /api/3/futures/order/{client_order_id}

Returns the successfully canceled futures order.

Requires the "Place/cancel orders" API key Access Right.

Response: futures order

Get Futures Position Parameters

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/config"

Response:

{
  "config": [
    {
      "symbol": "BTCUSD_PERP",
      "margin_call_leverage_mul": "1.20",
      "liquidation_leverage_mul": "2.00",
      "max_initial_leverage": "100.00",
      "margin_mode": "Isolated",
      "force_close_fee": "0.001",
      "enabled": true,
      "active": false,
      "limit_base": "5000000.000000000000",
      "limit_power": "1.25",
      "unlimited_threshold": "2.00"
    }
  ]
}

GET /api/3/futures/config

Returns information about futures position configuration.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name Type Description
symbol String Trading symbol.
margin_call_leverage_mul Number Multiplier applied to a requested leverage for calculating margin call price.
liquidation_leverage_mul Number Multiplier applied to a requested leverage for calculating liquidation price.
max_initial_leverage Number Maximum leverage that the user can use for margin trading.
margin_mode String Mode of margin trading.
Possible values: Isolated, Cross
force_close_fee Number Fee for the force closing of the position.
enabled Boolean Is margin trading available.
active Boolean Are there any positions which comply with the parameters (including not yet opened).
limit_base Number Optional. An absolute maximum that a position value can reach. Returns only if the risk limit exists.
limit_power Number Optional. Power which determines the influence of the leverage on the risk limit value. Returns only if the risk limit exists.
unlimited_threshold Number Optional. Position leverage below which the risk limit is not calculated. Returns only if the risk limit exists.

Risk Limits

Risk limits are a set of upper boundaries to the position value regarding the chosen leverage. Thus, each user leverage has its individual limit calculated according to the configuration as follows:

Risk limit = limit_base / ( L ^ limit_power ),

where L is a leverage set by the user.

Note that the resulting limit hedges the value of existing open orders (considering unfilled portion of their quantity) added to the position market value and the value of a new order.

Get All Trading Commissions

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/fee"

Response:

[
  {
    "symbol": "BTCUSDT_PERP",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC_PERP",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
]

GET /api/3/futures/fee

Returns personal trading commission rates for all contracts.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Trading Commission

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/fee/ETHBTC_PERP"

Response:

{
  "symbol": "ETHBTC_PERP",
  "take_rate": "0.001",
  "make_rate": "-0.0001"
}

GET /api/3/futures/fee/{symbol}

Returns personal trading commission rate by contract.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Futures Trading History

Futures Orders History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/history/order?symbol=ETHBTC_PERP"
[
  {
    "id": 828680665,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.055487",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:47.321Z",
    "updated_at": "2024-04-19T15:23:54.876Z"
  },
  {
    "id": 828680667,
    "client_order_id": "f4307c6e507e49019907c917b6d7a084",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "status": "partiallyFilled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "13.942",
    "price": "0.011384",
    "price_average": "0.045000",
    "quantity_cumulative": "5.240",
    "margin_mode": "isolated",
    "created_at": "2024-04-16T14:18:50.321Z",
    "updated_at": "2024-04-19T15:23:56.876Z"
  }
]

GET /api/3/futures/history/order

Returns all futures orders. Orders without executions are deleted after 24 hours.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
client_order_id String If set, other parameters will be ignored, including limit and offset.
symbol String Comma-separated symbol codes.
from DateTime Interval initial value.
till DateTime Interval end value.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Symbol code.
side String Trade side.
Possible values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — order quantity filled completely.
canceled — an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
quantity_cumulative Number Executed order quantity.
display_quantity String The visible part of the hidden order quantity.
price Number Order price.
price_average Number Average price of executed order quantity.
expire_time DateTime Date of order expiration. Specified if time_in_force is GTD.
position_id Number Optional. Position identifier of the order.
stop_price Number The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
created_at DateTime Date of order's creation.
updated_at DateTime Date of order's last update.
order_list_id String Optional. Order list identifier.
contingency_type String Optional. Order list type.
Possible values: oneCancelOther, oneTriggerOther, oneTriggerOneCancelOther
margin_mode String Margin mode.
Possible values: isolated, cross
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.

Futures Trades History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/history/trade?symbol=ETHBTC_PERP"
[
  {
    "id": 9535486,
    "order_id": 816088377,
    "client_order_id": "f8dbaab336d44d5ba3ff578098a68454",
    "symbol": "ETHBTC_PERP",
    "side": "sell",
    "quantity": "0.061",
    "price": "0.045487",
    "fee": "0.000002775",
    "timestamp": "2024-04-17T12:32:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  },
  {
    "id": 9535437,
    "order_id": 816088021,
    "client_order_id": "27b9bfc068b44194b1f453c7af511ed6",
    "symbol": "ETHBTC_PERP",
    "side": "buy",
    "quantity": "0.038",
    "price": "0.046000",
    "fee": "-0.000000174",
    "timestamp": "2024-04-17T12:30:57.848Z",
    "margin_mode": "isolated",
    "taker": true
  }
]

GET /api/3/futures/history/trade

Get the user's futures trading history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
order_id Number Unique order identifier as assigned by exchange.
position_id Number Position identifier of the taker's order in the trade.
symbol String Comma-separated symbol codes.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
by String Filter type.
Accepted values: timestamp, id
Default value: id
from DateTime or Number Interval initial value. If sorting by timestamp is used, then DateTime; otherwise Number.
till DateTime or Number Interval end value. If sorting by timestamp is used, then DateTime; otherwise Number.
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
id String Trade unique identifier as assigned by exchange.
order_id String Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader. The order history may list several orders with the same client_order_id.
symbol String Contract code.
side String Trade side.
Possible values: sell, buy
quantity Number Trade quantity.
price Number Trade price.
fee Number Trade commission.
Can be negative ("rebate" — reward paid to the trader). See fee currency in the symbol config.
timestamp DateTime Trade timestamp.
taker Boolean Liquidity indicator.
position_id Number Optional. Position identifier of the taker's order in the trade.
pnl Number Optional. Realized Profit and Loss on this trade
liquidation Boolean Optional. Whether it is a liquidation trade.
margin_mode String Margin mode.
Possible values: isolated, cross

Futures Positions History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/history/positions"
[
  {
    "id":3001,
    "entry_value": "0",
    "entry_price": "0.000",
    "avg_buy_price": "1978.057",
    "avg_sell_price": "3851.001",
    "quantity": "0",
    "margin_call_price": "0.000",
    "liquidation_price": "0.000",
    "bankruptcy_price": "0.000",
    "margin": "100.169018395350",
    "required_margin": "0",
    "orders_margin": "0.000006557500",
    "pnl": "0.187294400000",
    "leverage": "10.00",
    "margin_mode": "isolated",
    "state": "closed",
    "symbol": "ETHUSDT_PERP",
    "margin_call": false,
    "create_timestamp": 1626881592397,
    "update_timestamp": 1639570624225
  }
]

GET /api/3/futures/history/positions

Get the futures positions history.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
from Number Interval initial value in nanoseconds. Minimum value: 1
till Number Interval end value in nanoseconds. Minimum value: 1
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000
by String The name of the field to order the results by (only sorting by update_timestamp is allowed).
Accepted values: ts, timestamp

Response:

Name Type Description
id Number Position identifier.
entry_value Number Position value in currency.
entry_price Number Weighted average open price.
avg_buy_price Number Weighted average buy price.
avg_sell_price Number Weighted average sell price.
quantity Number Position quantity.
margin_call_price Number If the market is equal to or worse than this price, a margin call will be issued.
liquidation_price Number The price at which the platform begins to close the position.
bankruptcy_price Number The price at which the position can no longer be closed with any non-negative PnL.
margin Number Amount of margin expressed in the quote currency.
required_margin Number Margin reserved for close orders.
orders_margin Number Margin reserved for open orders.
pnl Number Unrealized Profit and Loss.
leverage Number Position leverage.
margin_mode String Mode of margin trading.
Possible values: isolated, cross
state String Position state.
Possible values: closed, active, liquidated
fee_cumulative String Total amount of fees paid throughout the position lifetime until it is closed.
This value does zero out after the position closes and does not when it flips.
symbol String Contract code.
margin_call Boolean Flag indicating the position is close to the liquidation, and increased margin may prevent it from happening.
create_timestamp Number Timestamp of position creation in nanoseconds.
update_timestamp Number Timestamp of position update in nanoseconds.

Futures Clearing Details

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/futures/history/clearing"
[
  {
    "timestamp": 1646524800267,
    "position_id": 972,
    "position_quantity": "0.00010",
    "position_entry_value": "5.126379000000",
    "type": "funding",
    "symbol": "BTCUSDT_PERP",
    "currency": "USD",
    "amount": "-0.011819526000",
    "rate": "0.003",
    "debt_delta": "0"
  }
]

GET /api/3/futures/history/clearing

Get clearing details.

Requires the "Orderbook, History, Trading balance" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
currency String Quote currency code.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
from Number Interval initial value in nanoseconds. Minimum value: 1
till Number Interval end value in nanoseconds. Minimum value: 1
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000

Response:

Name Type Description
timestamp Number Transfer timestamp in nanoseconds.
position_id Number Optional. Position identifier.
position_quantity Number Optional. Position quantity.
position_entry_value Number Optional. Position value in currency.
type String Transfer type.
Possible values: funding
symbol String Optional. Symbol code.
currency String Transfer currency.
amount Number Transfer amount.
rate Number Optional. Interest rate. It is null if the withdrawal occurred during a close trade (debt collection).
debt_delta Number Optional. Debt value. Returned if a user was unable to pay funding during the last withdrawal but had a positive UPnL.

User Management

Get API Keys

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/user/api-keys"
[
  {
    "api_key_first_six": "va5-9V",
    "key_name": "User Key 1",
    "exchange_read": true,
    "exchange_trade": true,
    "bank_read": true,
    "bank_withdraw": true,
    "allowed_ips": [
      "127.0.0.1",
      "127.0.0.1"
    ],
    "is_active": true,
    "created_at": "2023-03-22T15:04:05",
    "updated_at": "2023-03-22T15:04:05"
  }
]

GET /api/3/user/api-keys

Returns info about the current user's API keys.

Does not return API keys themselves.

Requires no API key Access Rights.

Response:

Name Type Description
api_key_first_six String First 6 symbols of the public key.
key_name String Name of the key.
exchange_read Boolean "Orderbook, History, Trading balance" API key access right.
exchange_trade Boolean "Place/cancel orders" API key access right.
bank_read Boolean "Payment information" API key access right.
bank_withdraw Boolean "Withdraw cryptocurrencies" API key access right.
allowed_ips []String Optional. A list of whitelisted IPs.
is_active Boolean Flag indicating the API key is active.
created_at String The date and time the key was created.
updated_at String The date and time the key was updated.

Wallet Management

Wallet Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/balance"

Response. All currencies:

[
  {
    "currency":"BTC",
    "available":"0.00005821",
    "reserved":"0.00001"
  },
  {
    "currency":"USDT",
    "available":"0.01",
    "reserved":"0"
  }
]

Response. One currency:

{
  "available":"0.00005821",
  "reserved":"0.00001"
}

GET /api/3/wallet/balance GET /api/3/wallet/balance/{currency}

Returns the user's wallet balances except zero balances.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Optional. Currency filter.

Response:

Name Type Description
currency String Currency code.
available Number Amount available for withdrawals or transfers to the trading account.
reserved Number Amount reserved for incomplete transactions (including the fee).

Get Whitelisted Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address/white-list"
{
  "addresses": [
    {
      "address": "3A3MR43kUvahSAJtTsxzE8mcTz3VfL9upi",
      "currency": "USDT",
      "name": "ETH withdrawal",
      "network": "ETH"
    }
  ]
}

GET /api/3/wallet/crypto/address/white-list

Returns whitelisted addresses.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
addresses []JSON Whitelisted addresses.
> name String Name of the whitelist item.
> currency String Currency code.
> network String Code of the currency of the hosting network.
> address String Address for deposits.

Get Deposit Crypto Address

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address?currency=BTC"
[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address

Get current addresses. Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Optional. Currency code.
network_code String Optional. Network code.

Response:

Name Type Description
currency String Optional. Currency code.
address String Address for deposits.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
public_key String Optional. An additional identifier required for specific currencies.
network_code String Optional. Network code.

Generate Deposit Crypto Address

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address" \
  -d "currency=BTC"
{
  "currency":"BTC",
  "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
}

POST /api/3/wallet/crypto/address

Creates a new deposit address. Existing addresses may still receive funds. For some tokens (e.g., Ethereum tokens), a single address is generated per base currency with additional identifiers which differ for each address: payment_id or public_key. As a result, generating a new address for such a token will change the current address for an entire base currency accordingly.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Currency code.
network_code String Optional. Network code.

Response:

Name Type Description
currency String Optional. Currency code.
address String Address for deposits.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
public_key String Optional. An additional identifier required for specific currencies.
network_code String Optional. Network code.

Last 10 Deposit Crypto Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address/recent-deposit?currency=BTC"
[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address/recent-deposit

Returns the last 10 unique addresses used for deposits (by currency).

Requires the "Payment information" API key Access Right.

Name Type Description
currency String Currency code.
network_code String Optional. Network code.

Response:

Name Type Description
currency String Optional. Currency code.
address String Address for deposits.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
public_key String Optional. An additional identifier required for specific currencies.
network_code String Optional. Network code.

Last 10 Withdrawal Crypto Addresses

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address/recent-withdraw?currency=BTC"
[
  {
    "currency":"BTC",
    "address":"3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
]

GET /api/3/wallet/crypto/address/recent-withdraw

Returns the last 10 unique addresses used for withdrawals (by currency).

Requires the "Payment information" API key Access Right.

Name Type Description
currency String Currency code.
network_code String Optional. Network code.

Response:

Name Type Description
currency String Optional. Currency code.
address String Address for deposits.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
public_key String Optional. An additional identifier required for specific currencies.
network_code String Optional. Network code.

Withdraw Crypto

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/withdraw" \
  -d "currency=BTC&amount=0.001&address=3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv&auto_commit=false"

Success response:

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

Validation error:

{
  "error": {
    "code": 10001,
    "message": "Validation error",
    "description": "Invalid currency: fiat"
  }
}

Invalid currency error:

{
  "error": {
    "code": 2002,
    "message": "Currency not found",
    "description": "The requested currency can't be found. Requested: USD"
  }
}

Insufficient funds error:

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

Limits exceeded error:

{
  "error": {
    "code": 20003,
    "message": "Limit exceeded",
    "description": "Withdrawal limit exceeded"
  }
}

POST /api/3/wallet/crypto/withdraw

Withdraw crypto. The transaction gets the status CREATED right after the creation.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Please take note that changing security settings affects withdrawals:

Parameters:

Name Type Description
currency String Currency code.
network_code String Optional. Network code.
amount Number The amount that will be sent to the specified address.
address String Address identifier.
wallet_id String Optional. Wallet ID.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
include_fee Boolean Default value: false
If true is set, then total spent value will include fees.
auto_commit Boolean Default value: true
If false is set, then you should commit or rollback a transaction in an hour. Used in two-phase commit schema.
use_offchain String Whether the withdrawal may be committed off-chain.
Accepted values: never, optionally, required
Default value: never
public_comment String Optional. Maximum length is 255.

Response:

Name Type Description
id String Transaction unique identifier.

Convert Between Currencies

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/convert" \
  -d "from_currency=USDT20&to_currency=USDT&amount=0.01"
{
  "result": [
    "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b",
    "d2ce57hf-6g7d-4ka0-b8aa-4a27e5ee5i7b"
  ]
}

POST /api/3/wallet/convert

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
from_currency String Currency code.
to_currency String Currency code.
amount Number The amount that will be sent to the specified address.

Response:

Name Type Description
result []JSON Transaction unique identifiers as assigned by exchange.

Withdraw Crypto Commit or Rollback

curl \
  -X PUT \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/withdraw/d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
{
  "result": true
}

PUT /api/3/wallet/crypto/withdraw/{id}

Commit a withdrawal. The transaction gets the status PENDING.

DELETE /api/3/wallet/crypto/withdraw/{id}

Roll back a withdrawal.

If the auto_commit parameter has been set to false while sending the request for withdrawing crypto, the withdrawal needs to be committed or rolled back one hour after the request. Use PUT /api/3/wallet/crypto/withdraw/{id} to approve the withdrawal operation, or DELETE /api/3/wallet/crypto/withdraw/{id} to discard it.

The id parameter must contain the unique transaction identifier value received as a result of the POST /api/3/wallet/crypto/withdraw request.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
id String Transaction unique identifier returned to a POST /api/3/wallet/crypto/withdraw request.

Both methods are idempotent.

Response:

Name Type Description
result Boolean true if the request is completed.

Check If Crypto Address Belongs to Current Account

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/address/check-mine?address=1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"
{
  "result": true
}

GET /api/3/wallet/crypto/address/check-mine

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
address String Address.

Response:

Name Type Description
result Boolean true if the address belongs to the current account.

Transfer Between Wallet and Exchange

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/transfer" \
  -d "currency=eth&amount=0.01&source=wallet&destination=spot"
[
  "d2ce578f-647d-4fa0-b1aa-4a27e5ee597b"
]

POST /api/3/wallet/transfer

Transfers funds from the wallet to the exchange account to make them available for trading.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Currency code.
amount Number The amount that will be transferred between accounts.
source String Transfer source account type.
Accepted values: wallet, spot, derivatives. Must not be the same as destination.
destination String Transfer destination accounts type.
Accepted values: wallet, spot, derivatives. Must not be the same as source.

Response:

Name Type Description
[]String Transaction unique identifier as assigned by exchange.

Transfer Money to Another User

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/internal/withdraw" \
  -d "by=email&identifier=user@example.com&currency=BTC&amount=0.001"
{
  "result": "fd3088da-31a6-428a-b9b6-c482673ff0f2"
}

POST /api/3/wallet/internal/withdraw

Creates and commits an off-chain withdrawal from the wallet of one exchange user to the wallet of another exchange user.

Apart from available balance, the amount of a withdrawal must exceed the sum of:

An operation may fail due to the following reasons:

Call GET /api/3/public/currency/{currency} and check payout_enabled to determine if withdrawals are allowed for the currency.

Call GET /api/3/wallet/transactions/{id} to check out the status of resulting transaction.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
currency String Currency code.
amount Number The amount that will be transferred.
by String Type of the beneficiary identifier specified below. Accepted values: email, username, external_id
identifier String Beneficiary identifier value. Either email, external identifier, or username.
public_comment String Optional text comment for the external usage. Can be up to 255 characters long, excluding the following characters: &, ', <, >, "

Response:

Name Type Description
result String Transaction unique identifier as assigned by exchange.

Get Transactions History

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/transactions?currencies=ETH,BTC&sort=DESC"
[
  {
    "id": 50844835,
    "created_at": "2024-04-22T21:03:04.111Z",
    "updated_at": "2024-04-22T21:04:41.487Z",
    "last_activity_at": "2024-04-30T15:42:12.274495Z",
    "status": "SUCCESS",
    "type": "WITHDRAW",
    "subtype": "BLOCKCHAIN",
    "native": {
      "tx_id": "27fa7f14-ca49-42fd-834a-4ce630d069d2",
      "index": 1071885589,
      "currency": "ETH",
      "amount": "0.01042",
      "fee": "0.00958",
      "hash": "0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20",
      "address": "0xd959463c3fcb222124bb7bb642d6a6573a6c5aba",
      "confirmations": 20
    }
  },
  {
    "id": 36896428,
    "created_at": "2024-04-12T10:27:26.135Z",
    "updated_at": "2024-04-12T10:42:29.065Z",
    "last_activity_at": "2024-04-30T15:42:13.274495Z",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "subtype": "BLOCKCHAIN",
    "native": {
      "tx_id": "a271ad64-5f34-4115-a63e-1cb5bbe4f67e",
      "index": 429625504,
      "currency": "BTC",
      "amount": "0.04836614",
      "hash": "4d7ae7c9d6fe84405ae167b3f0beacx8c68eb5a9d5189bckeb65d5e306427oe6",
      "address": "3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv",
      "confirmations": 2,
      "senders": [
        "0xd959463c3fcb0d2124bb7ac642d6a6573a6c5aba"
      ]
    },
    "operation_id": "99e78bf4-a708-43a3-ab18-e8e7618cd891"
  }
]

GET /api/3/wallet/transactions

Returns all transactions or a number of transactions by identifiers.

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
from DateTime Interval initial value (inclusive).
The value type depends on order_by.
till DateTime Interval end value (inclusive).
The value type depends on order_by.
types String Comma-separated transaction types.
subtypes String Comma-separated transaction subtypes.
statuses String Comma-separated transaction statuses.
Accepted values: CREATED, PENDING, FAILED, SUCCESS, ROLLED_BACK
currencies String Comma-separated currency codes.
networks String Comma-separated network codes.
id_from Number Index interval initial value.
Accepted values: 0 or greater
id_till Number Index interval end value.
Accepted values: 0 or greater
tx_ids String Comma-separated transaction identifiers.
order_by String The field the entries sorted by.
Accepted values: id, created_at, updated_at, last_activity_at, ID, CREATED_AT, UPDATED_AT, LAST_ACTIVITY_AT
Default value: created_at
Cannot be id or ID if from and (or) till are provided.
sort String Sort direction.
Accepted values: DESC, ASC
Default value: DESC
limit Number Default value: 100
Maximum value: 1000
offset Number Default value: 0
Maximum value: 100000
group_transactions Boolean Flag indicating whether the returned transactions will be parts of a single operation.
Default value: false

GET /api/3/wallet/transactions/{id}

Returns transaction by identifier.

Requires the "Payment information" API key Access Right.

Response:

Name Type Description
id Number Transaction unique identifier as assigned by exchange.
status String Transaction status.
Possible values: CREATED, PENDING, FAILED, SUCCESS, ROLLED_BACK
type String Transaction type.
subtype String Transaction subtype.
created_at DateTime Date of transaction creation.
updated_at DateTime Date and time of the last transaction update.
last_activity_at DateTime Date and time of the last transaction info update.
native Native Optional. Transaction native attributes as assigned by the platform.
operation_id String Optional. UUID of the operation embracing the transaction.
commit_risk Commit Risk Optional. Deposit risk score info.

Commit Risk model consists of:

Name Type Description
score Number Risk score that decreases non-linearly when the transaction gains confirmations.
Scores from 0 to 50 imply the transaction may be considered committed (but it is not guaranteed) or it may take at least half an hour otherwise.
Possible values: 0100
rbf Boolean Flag indicating whether the transaction did not gain a sufficient number of confirmations and may be replaced by another one for an additional fee.
This value indicates the transaction is complete and does not affect the score.
false value along with a score above 50 gives a good chance that the transaction is irreversible.
low_fee Boolean Flag indicating whether the actual network fee is lower than the estimated one.
This value indicates the difference between the estimated fee and the actual paid fee and does not affect the score.

Native model consists of:

Name Type Description
tx_id String Transaction unique identifier as assigned by exchange.
network_code String Optional. Network code.
protocol_code String Optional. The protocol or the standard powering the network.
wallet_id String Wallet ID.
index Number Internal index value that represents when the entry was updated.
currency String Currency code.
amount Number Amount of funds.
fee Number Payment commission value.
address String Address identifier.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
hash String Transaction hash.
offchain_id String Transaction identifier of external system.
confirmations Number Current count of confirmations for transaction in network.
public_comment String Optional. Custom text comment for external use.
error_code String Payout error reason.
Possible values: INVALID_ADDRESS, INVALID_PAYMENT_ID, BAD_PRECISION
senders []String Senders for this payin transaction. Displayed only for deposits.
operation_type String Operation type.
Possible values: SWAP
attempt_hashes []String Optional. Hash of the attempt to send a transaction to the blockchain.

type field may have the following values:

Type Description
DEPOSIT Deposit to a wallet address.
WITHDRAW Withdrawal to another crypto address.
TRANSFER Transfer of funds between wallet and trading accounts.
SWAP Exchange funds between different wallets.

subtype field may have the following values:

Type Subtype Description
DEPOSIT,
WITHDRAW
UNCLASSIFIED Deposit or withdrawal of fiat or crypto.
DEPOSIT,
WITHDRAW
BLOCKCHAIN Deposit or withdrawal of crypto committed to the Blockchain.
DEPOSIT,
WITHDRAW
OFFCHAIN Deposit or withdrawal of crypto offchain.
DEPOSIT,
WITHDRAW
FIAT Fiat deposit or withdrawal.
DEPOSIT,
WITHDRAW
SUB_ACCOUNT Transfer between subaccounts.
TRANSFER WALLET_TO_SPOT Transfer from a wallet to a spot trading account.
TRANSFER SPOT_TO_WALLET Transfer from a futures trading account to a wallet.
TRANSFER WALLET_TO_DERIVATIVES Transfer from a wallet to a futures trading account.
TRANSFER DERIVATIVES_TO_WALLET Transfer from a futures trading account to a wallet.
SWAP CHAIN_SWITCH_FROM Transferring funds from an original wallet during a conversion.
SWAP CHAIN_SWITCH_TO Transferring funds to a target wallet during a conversion.
DEPOSIT AIRDROP Claimed airdrop payment.

status field may have the following values:

Name Description
CREATED The transaction has been created and needs to be approved. For withdrawals, the status means that the transaction has been created but not committed. It remains in this status until manually validated or moved to a blockchain.
PENDING The transaction has been created and is queued until the fees are paid and it can be processed further. Also, for withdrawals and deposits, the status means that blockchain confirmations have not yet been gathered.
FAILED The transaction could not be committed.
ROLLED_BACK The transaction has been canceled.
SUCCESS The transaction has been approved and fully processed.

Check If Offchain is Available

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/check-offchain-available" \
  -d "currency=ETH&address=0xfaEF4bE10dDF50B68c220c9ab19381e20B8EEB2B"
{
  "result": true
}

POST /api/3/wallet/crypto/check-offchain-available

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Currency code.
address String Address identifier.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").

Response:

Name Type Description
result String true if an offchain transaction is available to the specified address.

Estimate Withdrawal Fees

curl \
  -X POST -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/fees/estimate" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "amount": "12",
          "currency": "BTC"
        }
      ]'
[
  {
    "fee": "0.09",
    "networkFee": "0",
    "amount": "12",
    "currency": "btc"
  }
]

POST /api/3/wallet/crypto/fees/estimate

Returns estimated fees charged for processing of on-chain withdrawals for provided combination of currency and network.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
* []JSON Combinations of currencies, networks, and amounts.
> currency String Currency code.
> amount Number The amount that will be deposited.
> network_code String Optional. Network code.

Response:

Name Type Description
* []JSON Combinations of fees, currencies, networks, and amounts.
> fee Number Estimated withdrawal fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.
> networkFee Number Network fee.
> amount Number The amount that will be withdrawn.
> currency String Currency code.
> networkCode String Optional. Network code

Estimate Withdrawal Fee

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/fee/estimate?currency=BTC&amount=0.01"
{
  "fee": "0.0008"
}

GET /api/3/wallet/crypto/fee/estimate

Returns estimated fee charged for processing on-chain withdrawals for provided combination of currency and network.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Currency code.
amount Number The amount that will be withdrawn.
network_code String Optional. Network code.

Response:

Name Type Description
fee String Estimated withdrawal fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.

Bulk Estimate Withdrawal Fee

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/fee/estimate/bulk" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "amount": "12",
          "currency": "BTC"
        }
      ]'
[
  {
    "fee": "1.21",
    "currency": "BTC",
    "amount": "12"
  }
]

POST /api/3/wallet/crypto/fee/estimate/bulk

Returns estimated fees charged for processing on-chain withdrawals for provided combinations of currencies and networks.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
* []JSON Combinations of currencies, networks, and amounts.
> currency String Currency code.
> amount Number The amount that will be deposited.
> network_code String Optional. Network code.

Response:

Name Type Description
* []JSON Combinations of fees, currencies, networks, and amounts.
> fee String Estimated deposit fee considering user's personal settings. The fee value is guaranteed not to change until the transaction is committed.
> currency String Currency code.
> amount Number The amount that will be deposited.
> network_code String Optional. Network code.

Get Withdrawal Fees Hash

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/crypto/fee/withdraw/hash"
{
  "hash": "3982183395978"
}

GET /api/3/wallet/crypto/fee/withdraw/hash

Returns the hash for withdrawal fees.

Requires the "Payment information" API key Access Right.

Response:

Name Type Description
hash String Fees hash.

Airdrops

Get Airdrops

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/airdrops"
[
  {
    "id": 3,
    "created_at": "2021-07-29T12:07:09.883538Z",
    "updated_at": "2021-08-04T12:54:59.301077Z",
    "currency": "BTC",
    "base_currency": "usd",
    "description": "test airdrop",
    "start_time": "2021-07-19T07:00:00Z",
    "end_time": "2022-07-19T07:00:00Z",
    "amount": "0.1",
    "status": "committed",
    "transaction_id": "85032346-7b90-4bdc-85ee-1f01e2390076"
  }
]

GET /api/3/wallet/airdrops

The request above returns the list of Airdrops.

Requires the "Payment information" API key Access Right.

All parameters are optional.

Parameters:

Name Type Description
currency String The code of dropped currency.
base_currency String The code of base currency (the currency used for dropped currency amount calculation).
active_at DateTime The request returns Airdrops, active at the specified moment.
Default value: now
statuses []String An array of desired Airdrop statuses.
Accepted values:
available — ready for claiming;
claimed — the Airdrop has been requested already;
pending — the payment is in progress;
committed — the payment is finished.
transaction_id String Airdrop transaction identifier.

Response:

Name Type Description
id Number Airdrop identifier.
created_at DateTime The moment when an Airdrop was created.
updated_at DateTime The moment when an Airdrop was changed.
currency String The code of dropped currency.
base_currency String The code of base currency (the currency used for dropped currency amount calculation).
description String Text note.
start_time DateTime The moment when an Airdrop claiming became available for the users.
end_time DateTime The moment when an Airdrop claiming will become unavailable for the users.
amount String The user's claimed amount.
status String Airdrop status.
Possible values:
available — ready for claim;
claimed — the Airdrop has been requested already;
pending — the payment is in progress;
committed — the payment is finished.
transaction_id String Optional. Airdrop transaction identifier.

Claim Airdrop

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/airdrops/3/claim" \
  -d "currency=BTC"
{}

POST /api/3/wallet/airdrops/{id}/claim

Claim an airdrop by its identifier.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
currency String The code of dropped currency.

Get Amount Locks

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/wallet/amount-locks?currency=BTC"
[
  {
    "id": 1,
    "currency": "BTC",
    "amount": "12.023",
    "date_end": "",
    "description": "default",
    "canceled": false,
    "canceled_at": null,
    "cancel_description": null,
    "created_at": "2021-07-29T12:07:09.883538Z"
  }
]

GET /api/3/wallet/amount-locks

Returns a list of amount locks.

Amount locks allow setting the minimum user's balance to determine their solvency. The locked amount is not displayed in the user's balances.

Amount locks are not tied to a currency. All locks in total affect the ability to withdraw the balance in any currency.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
currency String Optional. Currency code.
active Boolean Optional. Value showing whether the lock is active.
limit Number Default value: 100
Accepted range: 01000
offset Number Optional
Default value: 0
Minimum value: 0

Response:

Name Type Description
id Number Lock identifier.
currency String Currency code.
amount String Reserved amount.
date_end DateTime The date and time of the lock expiration.
description String Lock text description.
canceled Boolean Value showing whether the lock was canceled.
canceled_at DateTime The date and time at which the lock was canceled.
cancel_description String Text description on cancellation.
created_at DateTime The date and time of the lock was created.

Subaccounts

Get Subaccounts List

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account"

Response:

{
  "result": [
    {
      "sub_account_id": "179B5D",
      "email": "user+1@example.com",
      "status": "active"
    },
    {
      "sub_account_id": "179B5E",
      "email": "user+2@example.com",
      "status": "active"
    },
    {
      "sub_account_id": "179B5F",
      "email": "user+3@example.com",
      "status": "disable"
    }
  ]
}

Error response example:

Failed authorization:

{
  "error": {
    "code": 1002,
    "message": "Authorization is required or has been failed"
  }
}

Empty subaccount's list:

{
  "result": []
}

GET /api/3/sub-account

Returns list of subaccounts per a super account.

Requires no API key Access Rights.

Response:

Name Type Description
sub_account_id String Unique identifier of a subaccount. Hex number.
email String Email address of a subaccount.
status String User status of a subaccount. Possible values: new, active, disable

Freeze Subaccount

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/freeze" \
  -d "sub_account_ids=179B5D,179B5E"

Response:

{
  "result": true
}

Error response example:

Subaccounts are already frozen or disabled:

{
  "error": {
    "code": 21003,
    "message": "Sub account is already frozen or disabled"
  }
}

POST /api/3/sub-account/freeze

Freezes subaccounts listed. It implies that the Subaccounts frozen wouldn't be able to:

For any subaccount listed, all orders will be canceled and all funds will be transferred from the Trading balance.

Requires no API key Access Rights.

Parameters:

Name Type Description
sub_account_ids []String Subaccounts' identifiers separated by commas (,). Those could be obtained by the GET /api/3/sub-account request.

Response:

Name Type Description
result Boolean Value indicating whether subaccounts were successfully frozen.

Activate Subaccount

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/activate" \
  -d "sub_account_ids=179B5D,179B5E"

Response:

{
  "result": true
}

Error response example:

Subaccounts are disabled, and their functionality can't be restored through activation:

{
  "result": false
}

Failed authorization:

{
  "error": {
    "code": 1002,
    "message": "Authorization is required or has been failed"
  }
}

Wrong input data format:

{
  "error": {
    "code": 10001,
    "message": "Validation error"
  }
}

Subaccounts listed don't exist:

{
  "error": {
    "code": 21001,
    "message": "Subaccount not found"
  }
}

POST /api/3/sub-account/activate

Activates subaccounts listed. It would make subaccounts active after being frozen.

Requires no API key Access Rights.

Parameters:

Name Type Description
sub_account_ids []String Subaccounts' identifiers separated by commas (,). Those could be obtained by the GET /api/3/sub-account request.

Response:

Name Type Description
result Boolean Value indicating whether subaccounts were successfully activated.

Transfer to Subaccount

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/transfer" \
  -d "sub_account_id=179B5D&amount=1&currency=BTC&type=to_sub_account"

Response:

{
  "result": "ae37e806-0191-45fc-8c49-18137274772c"
}

Error response example:

Insufficient permissions:

{
  "error": {
    "code": 1003,
    "message": "Action is forbidden for this API key"
  }
}

Subaccount is frozen or disabled:

{
  "error": {
    "code": 21004,
    "message": "Sub account is already frozen or disabled"
  }
}

Insufficient funds:

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

POST /api/3/sub-account/transfer

Transfers funds from the super account to a subaccount or from a subaccount to the super account.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
sub_account_id Number Identifier of a subaccount to deposit/withdraw funds.
amount Number Amount of funds to be transferred.
currency String Name (code) of base currency (e.g., "BTC").
type String Type of transaction. Accepted values: to_sub_account, from_sub_account

Response:

Name Type Description
result String Identifier of the transaction resulting.

Transfer to Super Account

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/transfer/sub-to-super" \
  -d "sub_amount=1&currency=BTC"

Response:

{
  "result": "5638da11-a381-477c-9224-37c252583a70"
}

POST /api/3/sub-account/transfer/sub-to-super

Creates and commits a transfer from a subaccount to its super account.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
amount Number Amount of funds to be transferred.
currency String Name (code) of base currency (e.g., "BTC").

Response:

Name Type Description
result String Identifier of the transaction resulting.

Transfer Across Subaccounts

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/transfer/sub-to-sub" \
  -d "sub_account_id=179B5D&amount=1&currency=BTC"

Response:

{
  "result": "f85edb8e-d2bc-4810-80a6-10a08a505e5f"
}

POST /api/3/sub-account/transfer/sub-to-sub

Creates and commits a transfer between the user (subaccount) and another subaccount.

Requires the "Withdraw cryptocurrencies" API key Access Right.

Parameters:

Name Type Description
sub_account_id Number Identifier of a subaccount.
amount Number Amount of funds to be transferred.
currency String Name (code) of base currency (e.g., "BTC").

Response:

Name Type Description
result String Identifier of the transaction resulting.

Get ACL Settings

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/acl?sub_account_ids=179B5D,179B5E"

Response:

{
  "result": [
    {
      "sub_account_id": "179B5E",
      "deposit_address_generation_enabled": true,
      "withdraw_enabled": true,
      "description": "",
      "created_at": "2021-07-30T14:50:08.621Z",
      "updated_at": "2021-07-30T14:50:08.621Z"
    }
  ]
}

Error response example:

Insufficient permissions:

{
  "error": {
    "code": 1003,
    "message": "Action is forbidden for this API key"
  }
}

Subaccount is frozen or disabled:

{
  "error": {
    "code": 21004,
    "message": "Sub account is already frozen or disabled"
  }
}

GET /api/3/sub-account/acl

Returns a list of withdrawal settings for subaccounts listed.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
sub_account_ids []String Optional. Subaccounts' identifiers separated by commas (,). Those could be obtained by the GET /api/3/sub-account request.

Response:

Name Type Description
sub_account_id String Unique identifier of a subaccount.
deposit_address_generation_enabled Boolean Value indicating the desired state of deposits.
withdraw_enabled Boolean Value indicating the desired state of withdrawals.
description String Textual description. Normally left empty.
created_at DateTime ACL creation time.
updated_at DateTime ACL update time.

Change ACL Settings

curl \
  -X POST \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/acl" \
  -d "sub_account_ids=179B5E&deposit_address_generation_enabled=true&withdraw_enabled=true"

Response:

{
  "result": [
    {
      "sub_account_id": "179B5E",
      "deposit_address_generation_enabled": true,
      "withdraw_enabled": true,
      "description": "",
      "created_at": "2021-07-30T14:50:08.621Z",
      "updated_at": "2021-07-30T14:50:08.621Z"
    }
  ]
}

Error response example:

Subaccount is frozen or disabled:

{
  "error": {
    "code": 21004,
    "message": "Sub account is already frozen or disabled"
  }
}

Insufficient permissions:

{
  "error": {
    "code": 1003,
    "message": "Action is forbidden for this API key"
  }
}

POST /api/3/sub-account/acl

Disables or enables withdrawals for a subaccount.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
sub_account_ids []String Subaccounts' identifiers separated by commas (,). Those could be obtained by the GET /api/3/sub-account request.
deposit_address_generation_enabled Boolean Value indicating the desired state of deposits.
withdraw_enabled Boolean Value indicating the desired state of withdrawals.
description String Textual description. Normally left empty.
created_at DateTime ACL creation time.
updated_at DateTime ACL update time.

Response:

Name Type Description
sub_account_id String Unique identifier of a subaccount.
deposit_address_generation_enabled Boolean Value indicating the desired state of deposits.
withdraw_enabled Boolean Value indicating the desired state of withdrawals.
description String Textual description. Normally left empty.
created_at DateTime ACL creation time.
updated_at DateTime ACL update time.

Get Subaccount Balance

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/balance/179B5E"

Response:

{
  "result": {
    "wallet": [
      {
        "currency": "1ST",
        "available": "0.0",
        "reserved": "0.0"
      }
    ],
    "derivatives": [
      {
        "currency": "1ST",
        "available": "0",
        "reserved": "0"
      }
    ],
    "spot": [
      {
        "currency": "1ST",
        "available": "0",
        "reserved": "0",
        "reserved_margin": "0",
        "cross_margin_reserved": "0"
      }
    ]
  }
}

Error response example:

Insufficient permissions:

{
  "error": {
    "code": 1003,
    "message": "Action is forbidden for this API key"
  }
}

GET /api/3/sub-account/balance/{sub_acc_id}

Returns non-zero balance values by subaccount identifier specified. Report will include the wallet and Trading balances for each currency. It is functional with no regard to the state of a subaccount. All account types are optional and appear only in case of non-zero balance.

Requires the "Payment information" API key Access Right.

Get Subaccount Crypto Address

curl \
  -u "apiKey:secretKey" \
  "https://api.hitbtc.com/api/3/sub-account/crypto/address/179B5E/BTC"

Response:

{
  "result": {
    "address": "3E8WKmTJzaTsBc4kvuEJVjPNtak6vQRcRv"
  }
}

GET /api/3/sub-account/crypto/address/{sub_acc_id}/{currency}

Returns subaccount crypto address for currency.

Requires the "Payment information" API key Access Right.

Parameters:

Name Type Description
network_code String Optional. Network code.

Response:

Name Type Description
address String Address for deposits.
payment_id String Optional. An additional identifier required for specific currencies (for example, "Memo").
public_key String Optional. An additional identifier required for specific currencies.

SOCKET API REFERENCE

Connection

The number of WebSoсket connections established per IP address cannot exceed 100.

Ping

wscat -c wss://api.hitbtc.com/api/3/ws/public -P

Ping messages

< Received ping
< Received ping
< Received ping

After a WebSocket connection is established, the system sends ping messages to the client each 30 seconds.

In order to see incoming ping messages, place -P flag after the endpoint.

Request Object

Request

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

An RPC call is represented by sending a Request object to a Server.

The Request object has the following members:

Notification

Notification

{
  "ch": "trades",
  "update": {
    "BTCUSDT": [{
      "t": 1626861123552,
      "i": 1555634359,
      "p": "30877.68",
      "q": "0.00006",
      "s": "sell"
    }]
  }
}

A Notification is a Request object without an id member. A Request object (a Notification) signifies the lack of the Client's interest in the corresponding Response object. Therefore, no Response objects need to be returned to the Client.

Response Object

When an RPC call is made, the server must reply with responses, except for notifications cases.

Response on success subscription is true. Example:

Response

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

Response error

{
  "error": {
    "code": 2001,
    "message": "Symbol not found",
    "description": "Symbol not found"
  },
  "id": 123
}

The Response is represented as a single JSON Object, with the following members:

Socket Market Data

In order to access market data via WebSocket interface, connect to the endpoint:

wscat -c wss://api.hitbtc.com/api/3/ws/public

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/1000ms",          // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

From that point on, you will be able to send request messages in JSON format with the following parameters:

Name Type Description
method String The name of the method to be invoked.
Accepted values: subscribe, unsubscribe, subscriptions
ch String Channel name.
params JSON Parameter values to be used during the method invocation. The set of parameters may vary depending on the channel chosen.
id String Optional. Request identifier as assigned by sender.

Response

{
  "result": {
    "ch": "orderbook/top/1000ms",        // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Any valid and successfully processed request will result in a JSON-formatted response message containing the following fields:

Name Type Description
result Result Details about resulting subscription status.
id String Optional. Request identifier as assigned by sender.

Result model consists of:

Name Type Description
ch String Channel name.
subscriptions []String List of active subscriptions.

Subscriptions

In case of a successful subscriptions, the server will send:

In the second case, the first snapshot comes right after the response if the limit parameter is greater than 0. Snapshot gives a full account of the market within the defined scope, and an update contains only recent changes which are being sent immediately.

Batch Notifications

If a market data request includes a number of subscriptions, a choice of channel will determine the distribution of updates over incoming notifications.

In the basic scenario, a single notification will contain data on a particular symbol only. Subscription to "batch" channels (ones ending with /batch) allows notifying via combined updates per multiple symbols.

Get Active Subscriptions

Request

{
  "method": "subscriptions",
  "ch": "trades",                        // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "trades",                      // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Method: subscriptions

Returns the list of all active subscriptions on a channel.

Subscribe to Trades

Request

{
  "method": "subscribe",
  "ch": "trades",                        // Channel
  "params": {
    "symbols": ["ETHBTC", "BTCUSDT"],
    "limit": 1
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "trades",                      // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "trades",                        // Channel
  "snapshot": {
    "BTCUSDT": [{
      "t": 1626861109494,                // Timestamp in milliseconds
      "i": 1555634969,                   // Trade identifier
      "p": "30881.96",                   // Price
      "q": "12.66828",                   // Quantity
      "s": "buy"                         // Side
    }]
  }
}

Notification update

{
  "ch": "trades",
  "update": {
    "BTCUSDT": [{
      "t": 1626861123552,
      "i": 1555634969,
      "p": "30877.68",
      "q": "0.00006",
      "s": "sell"
    }]
  }
}

Channel: trades

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols []String List of symbol codes.
limit Number Optional. Limit to returned entries.
Accepted values: 01000
Default value: 0 (no history returned)

Subscribe to Candles

Request

{
  "method": "subscribe",
    "ch": "candles/M1",                  // Channel
    "params": {
      "symbols": ["BTCUSDT"],
      "limit": 10
    },
    "id": 123
  }

Response

{
  "result": {
    "ch": "candles/M1",
    "subscriptions": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "candles/M1",                    // Channel
  "snapshot": {
    "BTCUSDT": [
      {
        "t": 1626860340000,              // Message timestamp
        "o": "30881.95",                 // Open price
        "c": "30890.96",                 // Last price
        "h": "30900.8",                  // High price
        "l": "30861.27",                 // Low price
        "v": "1.27852",                  // Base asset volume
        "q": "39493.9021811"             // Quote asset volume
      },
      {
        "t": 1626860400000,
        "o": "30888.33",
        "c": "30860.52",
        "h": "30889.53",
        "l": "30860.31",
        "v": "3.80019",
        "q": "117283.0686182"
      },
      {
        "t": 1626860460000,
        "o": "30858.39",
        "c": "30863.56",
        "h": "30864.89",
        "l": "30853.83",
        "v": "53.04288",
        "q": "1636858.7119248"
      }
    ]
  }
}

Notification update

{
  "ch": "candles/M1",
  "update": {
    "ETHBTC": [
      {
        "t": 1626860880000,
        "o": "0.060711",
        "c": "0.060749",
        "h": "0.060749",
        "l": "0.060711",
        "v": "12.2800",
        "q": "0.7455339675"
      }
    ]
  }
}

Channel: candles/{period}

Supported periods: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols []String List of symbol codes.
limit Number Optional. Limit to returned entries.
Accepted values: 01000
Default value: 0 (no history returned)

Subscribe to Converted Candles

Request

{
  "method": "subscribe",
  "ch": "converted/candles/M1",          // Channel
  "params": {
    "symbols": ["BTCUSDT"],
    "target_currency": "USDT",
    "limit": 10
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "converted/candles/M1",
    "subscriptions": [
      "BTCUSDT"
    ]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "converted/candles/M1",
  "target_currency": "USDT",
  "snapshot": {
    "BTCUSDT": [
      {
        "t": 1626860340000,              // Message timestamp
        "o": "30881.95",                 // Open price
        "c": "30890.96",                 // Last price
        "h": "30900.8",                  // High price
        "l": "30861.27",                 // Low price
        "v": "1.27852",                  // Base asset volume
        "q": "39493.9021811"             // Quote asset volume
      }
    ]
  }
}

Notification update

{
  "ch": "converted/candles/M1",
  "target_currency": "USDT",
  "update": {
    "ETHBTC": {
      "BTCUSDT": [
        {
          "t": 1626860340000,
          "o": "30881.95",
          "c": "30890.96",
          "h": "30900.8",
          "l": "30861.27",
          "v": "1.27852",
          "q": "39493.9021811"
        }
      ]
    }
  }
}

Channel: converted/candles/{period}

Supported periods: M1 (one minute), M3, M5, M15, M30, H1 (one hour), H4, D1 (one day), D7, 1M (one month)

Requires no API key Access Rights.

Parameters:

Name Type Description
symbols []String List of symbol codes.
target_currency String Target currency.
limit Number Optional. Limit to returned entries.
Accepted values: 01000
Default value: 0 (no history returned)

Subscribe to Price Rates

Request

{
  "method": "subscribe",
  "ch": "price/rate/1s",                 // Channel
  "params": {
    "currencies": [
      "ETH",
      "BTC"
    ],
    "target_currency": "USDT"
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "price/rate/1s",               // Channel
    "target_currency": "USDT",
    "subscriptions": ["ETH","BTC"]
  },
  "id": 123
}

Data notification

{
  "ch": "price/rate/1s",
  "target_currency": "USDT",
  "data": {
    "ETH": {
      "t": 1684490221380,                // Timestamp
      "r": "1810.155"                    // Rate
    }
  }
}

{
  "ch": "price/rate/1s",
  "target_currency": "USDT",
  "data": {
    "BTC": {
      "t": 1684487340001,
      "r": "26863.71"
    }
  }
}

Channel: price/rate/{speed}

Supported speed: 1s, 3s

Parameters:

Name Type Description
currencies []String List of currency codes. Value ["*"] means all symbols are selected.
target_currency String Quote currency.

Subscribe to Price Rates in Batches

Request

{
  "method": "subscribe",
  "ch": "price/rate/1s/batch",           // Channel
  "params": {
    "currencies": [
      "ETH",
      "BTC"
    ],
    "target_currency": "USDT"
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "price/rate/1s/batch",         // Channel
    "target_currency": "USDT",
    "subscriptions": [
      "ETH",
      "BTC"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "price/rate/1s/batch",
  "target_currency": "USDT",
  "data": {
    "ETH": {
      "t": 1684490221380,                // Timestamp
      "r": "1810.155"                    // Rate
    },
    "BTC": {
      "t": 1684487340001,
      "r": "26863.71"
    }
  }
}

Channel: price/rate/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name Type Description
currencies []String List of currency codes. Value ["*"] means all symbols are selected.
target_currency String Quote currency.

Subscribe to Mini Ticker

Request

{
  "method": "subscribe",
  "ch": "ticker/price/1s",               // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/price/1s",             // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/price/1s",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "o": "0.030781",                   // Open price
      "c": "0.060043",                   // Last price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577"                 // Quote asset volume
    }
  }
}

{
  "ch": "ticker/price/1s",
  "data": {
    "BTCUSDT": {
      "t": 1614815872030,
      "o": "32636.79",
      "c": "32085.51",
      "h": "33379.92",
      "l": "30683.28",
      "v": "11.90667",
      "q": "384081.1955629"
    }
  }
}

Channel: ticker/price/{speed}

Supported speed: 1s, 3s

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Mini Ticker in Batches

Request

{
  "method": "subscribe",
  "ch": "ticker/price/1s/batch",         // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/price/1s/batch",       // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/price/1s/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "o": "0.030781",                   // Open price
      "c": "0.060043",                   // Last price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577"                 // Quote asset volume
    },
    "BTCUSDT": {
      "t": 1614815872030,
      "o": "32636.79",
      "c": "32085.51",
      "h": "33379.92",
      "l": "30683.28",
      "v": "11.90667",
      "q": "384081.1955629"
    }
  }
}

Channel: ticker/price/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Ticker

Request

{
  "method": "subscribe",
  "ch": "ticker/1s",                     // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/1s",                   // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/1s",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.03329",                    // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.10565",                    // Best bid quantity
      "c": "0.031210",                   // Last price
      "o": "0.030781",                   // Open price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577",                // Quote asset volume
      "p": "0.000429",                   // Price change
      "P": "1.39",                       // Price change percent
      "L": 1182694927                    // Last trade identifier
    }
  }
}

{
  "ch": "ticker/1s",
  "data": {
    "BTCUSDT": {
      "t": 1614815872050,
      "a": "32289.55",
      "A": "0.41210",
      "b": "32286.67",
      "B": "1.70049",
      "c": "0.057069",
      "o": "0.030545",
      "h": "0.029653",
      "l": "0.031804",
      "v": "11.90667",
      "q": "384081.1955629",
      "p": "0.003131",
      "P": "2.77",
      "L": 1182694927
    }
  }
}

Channel: ticker/{speed}

Supported speed: 1s, 3s

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Ticker in Batches

Request

{
  "method": "subscribe",
  "ch": "ticker/1s/batch",               // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "ticker/1s/batch",             // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "ticker/1s/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000,                // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.03329",                    // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.10565",                    // Best bid quantity
      "c": "0.031210",                   // Last price
      "o": "0.030781",                   // Open price
      "h": "0.031788",                   // High price
      "l": "0.030733",                   // Low price
      "v": "62.587",                     // Base asset volume
      "q": "1.951420577",                // Quote asset volume
      "p": "0.000429",                   // Price change
      "P": "1.39",                       // Price change percent
      "L": 1182694927                    // Last trade identifier
    },
    "BTCUSDT": {
      "t": 1614815872050,
      "a": "32289.55",
      "A": "0.41210",
      "b": "32286.67",
      "B": "1.70049",
      "c": "0.057069",
      "o": "0.030545",
      "h": "0.029653",
      "l": "0.031804",
      "v": "11.90667",
      "q": "384081.1955629",
      "p": "0.003131",
      "P": "2.77",
      "L": 1182694927
    }
  }
}

Channel: ticker/{speed}/batch

Supported speed: 1s, 3s

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Full Order Book

Request

{
  "method": "subscribe",
  "ch": "orderbook/full",                // Channel
  "params": {
    "symbols": ["ETHBTC"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/full",              // Channel
    "subscriptions": ["ETHBTC"]
  },
  "id": 123
}

Notification snapshot

{
  "ch": "orderbook/full",                // Channel
  "snapshot": {
    "ETHBTC": {
      "t": 1626866578796,                // Timestamp in milliseconds
      "s": 27617207,                     // Sequence number
      "a": [                             // Asks
        ["0.060506", "0"],
        ["0.060549", "12.6431"],
        ["0.060570", "0"],
        ["0.060612", "0"]
      ],
      "b": [                             // Bids
        ["0.060439", "4.4095"],
        ["0.060414", "0"],
        ["0.060407", "7.3349"],
        ["0.060390", "0"]
      ]
    }
  }
}

Notification update

{
  "ch": "orderbook/full",
  "update": {
    "ETHBTC": {
      "t": 1626866578902,
      "s": 27617208,
      "a": [
        ["0.060508", "0"],
        ["0.060509", "2.5486"]
        ],
      "b": [
        ["0.060501", "3.9000"],
        ["0.060500", "3.0459"]
        ]
    }
  }
}

Channel: orderbook/full

Parameters:

Name Type Description
symbols []String List of symbol codes.

Subscribe to Partial Order Book

Request

{
  "method": "subscribe",
  "ch": "orderbook/D5/100ms",            // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/D5/100ms",          // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/D5/100ms",            // Channel
  "data": {
    "BTCUSDT": {
      "t": 1626958488996,                // Timestamp in milliseconds
      "s": 29472321,                     // Sequence number
      "a": [                             // Asks
        ["32091.84", "0.01016"],
        ["32091.85", "0.41484"],
        ["32095.82", "0.00705"],
        ["32095.95", "0.52001"],
        ["32097.04", "0.20518"]
      ],
      "b": [                             // Bids
        ["32089.29", "0.00228"],
        ["32088.70", "0.40315"],
        ["32084.29", "0.00616"],
        ["32084.27", "0.53169"],
        ["32078.89", "0.01016"]
      ]
    },
    "ETHBTC": {
      "t": 1626958488990,
      "s": 28438797,
      "a": [
        ["0.061873", "4.8257"],
        ["0.061887", "1.9938"],
        ["0.061912", "0.5427"],
        ["0.061913", "0.1696"],
        ["0.061914", "0.1575"]
      ],
      "b": [
        ["0.061867", "0.9868"],
        ["0.061858", "0.1598"],
        ["0.061854", "1.8327"],
        ["0.061850", "0.8125"],
        ["0.061842", "0.1763"]
      ]
    }
  }
}

Channel: orderbook/{depth}/{speed}

Supported depth: D5, D10, D20

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Partial Order Book in Batches

Request

{
  "method": "subscribe",
  "ch": "orderbook/D5/1000ms/batch",     // Channel
  "params": {
    "symbols": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/D5/1000ms/batch",   // Channel
    "subscriptions": ["ETHBTC","BTCUSDT"]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/D5/1000ms/batch",     // Channel
  "data": {
    "BTCUSDT": {
      "t": 1626958488996,                // Timestamp in milliseconds
      "s": 29472321,                     // Sequence number
      "a": [                             // Asks
        ["32091.84", "0.01016"],
        ["32091.85", "0.41484"],
        ["32095.82", "0.00705"],
        ["32095.95", "0.52001"],
        ["32097.04", "0.20518"]
      ],
      "b": [                             // Bids
        ["32089.29", "0.00228"],
        ["32088.70", "0.40315"],
        ["32084.29", "0.00616"],
        ["32084.27", "0.53169"],
        ["32078.89", "0.01016"]
      ]
    },
    "ETHBTC": {
      "t": 1626958488990,
      "s": 28438797,
      "a": [
        ["0.061873", "4.8257"],
        ["0.061887", "1.9938"],
        ["0.061912", "0.5427"],
        ["0.061913", "0.1696"],
        ["0.061914", "0.1575"]
      ],
      "b": [
        ["0.061867", "0.9868"],
        ["0.061858", "0.1598"],
        ["0.061854", "1.8327"],
        ["0.061850", "0.8125"],
        ["0.061842", "0.1763"]
      ]
    }
  }
}

Channel: orderbook/{depth}/{speed}/batch

Supported depth: D5, D10, D20

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Top of Book

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/1000ms",          // Channel
  "params": {
    "symbols": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/top/1000ms",        // Channel
    "subscriptions": ["ETHBTC", "BTCUSDT"]
  },
  "id": 123
}

Data notifications

{
  "ch": "orderbook/top/1000ms",
  "data": {
    "ETHBTC": {
      "t": 1626954648761,                // Timestamp in milliseconds
      "a": "0.062135",                   // Best ask
      "A": "4.1591",                     // Best ask quantity
      "b": "0.062124",                   // Best bid
      "B": "0.9877"                      // Best bid quantity
    }
  }
}

{
  "ch": "orderbook/top/1000ms",
  "data": {
    "BTCUSDT": {
      "t": 1626954648863,
      "a": "31936.09",
      "A": "1.30000",
      "b": "31933.40",
      "B": "0.00058"
    }
  }
}

Channel: orderbook/top/{speed}

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Top of Book in Batches

Request

{
  "method": "subscribe",
  "ch": "orderbook/top/100ms/batch",     // Channel
  "params": {
    "symbols": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "orderbook/top/100ms/batch",   // Channel
    "subscriptions": [
      "ETHBTC",
      "BTCUSDT"
    ]
  },
  "id": 123
}

Data notification

{
  "ch": "orderbook/top/100ms/batch",
  "data": {
    "ETHBTC": {
      "t": 1614815872000                 // Timestamp in milliseconds
      "a": "0.031175",                   // Best ask
      "A": "0.4033",                     // Best ask quantity
      "b": "0.031148",                   // Best bid
      "B": "0.3649",                     // Best bid quantity
    },
    "BTCUSDT": {
      "t": 1614815872005
      "a": "0.031175",
      "A": "0.4033",
      "b": "0.031148",
      "B": "0.3649",
    }
  }
}

Channel: orderbook/top/{speed}/batch

Supported speed: 100ms, 500ms, 1000ms

Parameters:

Name Type Description
symbols []String List of symbol codes. Value ["*"] means all symbols are selected.

Subscribe to Futures Information

Request

{
  "method": "subscribe",
  "ch": "futures/info",                  // Channel
  "params": {
    "symbols": ["*"]
  },
  "id": 123
}

Response

{
  "result": {
    "ch": "futures/info",                // Channel
    "subscriptions": ["BTCUSDT_PERP", "UFO-0115"]
  },
  "id": 123
}

Data notification

{
  "ch": "futures/info",
  "data": {
    "BTCUSDT_PERP": {
      "c": "perpetual",                 // Contract type
      "t": 1626861214235,               // Timestamp in milliseconds
      "m": "30873.48",                  // Mark price
      "i": "30871.12",                  // Index price
      "p": "0.000045936718467837",      // Premium index
      "P": "0.000087063368020112",      // Average premium index
      "o": "93.7128",                   // Open interest
      "r": "0.0001",                    // Funding rate
      "R": "0.0001",                    // Indicative funding rate
      "I": "0.0001",                    // Contract interest rate for one funding period
      "T": 1626883200000                // Next funding date
    }
  }
}

{
  "ch": "futures/info",
  "data": {
    "UFO-0715": {
      "c": "cash_settled",               // Contract type
      "t": 1640187241062,                // Timestamp in milliseconds
      "m": "1.34783",                    // Mark price
      "i": "1.33958",                    // Index price
      "o": "0",                          // Open interest
      "s": null,                         // Indicative settlement price
      "e": 1657886400000                 // Expiration date
    }
  }
}

Channel: futures/info

Parameters:

Name Type Description
symbols []String List of contract codes. Value ["*"] means all symbols are selected.

Socket Authentication

Basic

Examples with Basic algorithm:

wscat -c wss://api.hitbtc.com/api/3/ws/wallet
{
  "method": "login",
  "params": {
    "type": "BASIC",
    "api_key": "apiKey",
    "secret_key": "secretKey"
  }
}

Request method: login

Parameters:

Name Type Description
type String Encryption algorithm.
Accepted values: BASIC
api_key String API public key.
secret_key String API secret key.

HS256

Example with HS256 algorithm:


wscat -c wss://api.hitbtc.com/api/3/ws/wallet

{
  "method": "login",
  "params": {
    "type": "HS256",
    "api_key": "apiKey",
    "timestamp": 1626861109494,
    "signature": "secretKey"
  }
}

Signature generation example

from websocket import create_connection
import websocket
import json
from hashlib import sha256
from hmac import HMAC
from time import time


timestamp = int(time() * 1000)
api_key = "apiKey"
secret = "secretKey"
window = 10000
message = str(timestamp)

if window:
    message += str(window)

ws = create_connection('wss://api.hitbtc.com/api/3/ws/wallet')

sign = HMAC(key=secret.encode(),
            msg=message.encode(),
            digestmod=sha256).hexdigest()

res = ws.send(json.dumps({"method": "login", "params": {"type": "HS256", "api_key": api_key, "timestamp": timestamp, "window": window, "signature": sign}}))

print(ws.recv())

Request method: login

Parameters:

Name Type Description
type String Encryption algorithm.
Accepted values: HS256
api_key String API public key.
timestamp Number Timestamp.
window Number Optional. Maximum difference between timestamp and the moment of request processing in milliseconds.
Accepted range: 100060000
Default value: 10000
signature String HMAC SHA256 sign with API secret key.

Socket Trading

Trade via socket has some major differences compared to REST:

Socket Spot Trading

Subscribe to Reports

Request

wscat -c wss://api.hitbtc.com/api/3/ws/trading
{
  "method": "spot_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

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

Notification Spot orders snapshot

{
  "jsonrpc": "2.0",
  "method": "spot_orders",
  "params": [
    {
      "id": 584244931496,
      "client_order_id": "b5acd79c0a854b01b558665bcf379456",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "created_at": "2021-07-02T22:52:32.864Z",
      "updated_at": "2021-07-02T22:52:32.864Z",
      "report_type": "status"
    },
    {
      "id": 584246978340,
      "client_order_id": "eeb7d144eca545cd93d83078bc60b7f4",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.02",
      "post_only": false,
      "display_quantity": "0",
      "created_at": "2021-07-02T22:56:43.588Z",
      "updated_at": "2021-07-02T22:56:43.588Z",
      "report_type": "status"
    }
  ]
}

Notification Spot order update

{
  "jsonrpc": "2.0",
  "method": "spot_order",
  "params": {
    "id": 584244931496,
    "client_order_id": "b5acd79c0a854b01b558665bcf379456",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.01000",
    "quantity_cumulative": "0",
    "price": "0.01",
    "post_only": false,
    "display_quantity": "0",
    "created_at": "2021-07-02T22:52:32.864Z",
    "updated_at": "2021-07-02T22:52:32.864Z",
    "report_type": "new"
  }
}

Notification Spot trade

{
  "jsonrpc": "2.0",
  "method": "spot_order",
  "params": {
    "id": 626857425737,
    "client_order_id": "rqq6qnVTWvHa5YYG-7RviHLyA8JBu6Gj",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "filled",
    "type": "market",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "post_only": false,
    "created_at": "2021-08-23T16:29:24.006Z",
    "updated_at": "2021-08-23T16:29:24.006Z",
    "trade_id": 1361977606,
    "trade_quantity": "0.00001",
    "trade_price": "49595.04",
    "trade_fee": "0.001239876000",
    "trade_taker": true,
    "report_type": "trade"
  }
}

Method: spot_subscribe, spot_unsubscribe

Income methods: spot_order, spot_orders

Subscribes to execution reports of user's orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Response:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader.
symbol String Symbol code.
side String Trade side.
Accepted values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — (in updates) order quantity filled completely.
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
price Number Order price.
cum_quantity Number Cumulative executed quantity.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String The visible part of the hidden order quantity.
created_at DateTime Report creation date.
updated_at DateTime Date of the report's last update.
stop_price Number Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
expire_time DateTime Date of order expiration for time_in_force equal to GTD.
original_client_order_id String Identifier of replaced order.
trade_id Number Trade identifier. Required if report_type is trade.
trade_quantity Number Quantity of trade. Required if report_type is trade.
trade_price Number Trade price. Required if report_type is trade.
trade_fee Number Fee paid for trade. Required if report_type is trade.
trade_taker Boolean Liquidity indicator. Required if report_type is trade.
report_type String Report type.
Possible values:
status — (in snapshots) the record of an event occurred during the last snapshot period.
new — (in updates) an order has been placed in the order book (status is new).
suspended — (in updates) a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book (status is suspended).
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
rejected — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the status of the related canceled/replaced order will not change — i.e., it cannot be different from new, suspended, partiallyFilled). status is rejected.
expired — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (status is expired).
replaced — (in updates) an order cancel/replace request has been accepted and successfully processed (status is canceled, a new order placed instead has the new status value).
trade — (in updates) an order has been fully or partially executed (status is filled or partiallyFilled).

Get Active Spot Orders

Notification report

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583502239480,
      "client_order_id": "9be4d950d3c04485854ec5d7f260b1e8",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "created_at": "2021-07-01T23:04:04.048Z",
      "updated_at": "2021-07-01T23:04:04.048Z",
      "report_type": "status"
    }
  ],
  "id": 123
}

Method: spot_get_orders

Returns active orders.

Place New Spot Order

Request:

{
  "method": "spot_new_order",
  "params": {
    "client_order_id": "57d5525562c945448e3cbd559bd068c4",
    "symbol": "ETHBTC",
    "side": "sell",
    "type": "limit",
    "quantity": "0.015",
    "price": "0.059837"
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583565960004,
    "client_order_id": "57d5525562c945448e3cbd559bd06211",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "market",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "post_only": false,
    "created_at": "2021-07-02T00:58:05.307Z",
    "updated_at": "2021-07-02T00:58:05.307Z",
    "report_type": "new"
  },
  "id": 123
}

Example error response:

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

Method: spot_new_order

Creates a new spot order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Optional. Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Must be set to market, stopMarket, or takeProfitMarket if price was left unspecified.
Accepted values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
Default value: limit
time_in_force String Optional. Order type.
Accepted values: GTC, IOC, FOK, Day, GTD
Default value:
FOKtype is market, stopMarket, takeProfitMarket;
GTCtype is limit, stopLimit, takeProfitLimit.
quantity Number Order quantity.
price Number Order price. Required for limit types.
stop_price Number Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
expire_time DateTime Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol's tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
take_rate Number Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
make_rate Number Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Create New Spot Order List

Request:

{
  "method": "spot_new_order_list",
  "params": {
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "orders": [
      {
        "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
        "symbol": "ETHBTC",
        "side": "buy",
        "type": "limit",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "price": "0.046016",
        "display_quantity": "0",
        "post_only": false
      },
      {
        "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
        "symbol": "ETHBTC",
        "side": "sell",
        "type": "stopMarket",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "stop_price": "0.044050",
        "price": "0.044016",
        "display_quantity": "0",
        "post_only": false
      }
    ]
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "display_quantity": "0",
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  "id": 123
}
{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "display_quantity": "0",
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z"
  },
  "id": 123
}

Example error response:

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

Method: spot_new_order_list

Creates a new spot order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
order_list_id String Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to client_order_id of the first order in the request.
contingency_type String Order list type.
Accepted values:
allOrNone (AON) — all orders in the set should be executed within a single transaction or become expired otherwise;
oneCancelOther (OCO) — all orders in the set should be canceled if one of them was executed;
oneTriggerOther (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other;
oneTriggerOneCancelOther (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
orders []Order Orders in the list. There must be 2 or 3 orders for allOrNone/oneCancelOther/oneTriggerOther and 3 — for oneTriggerOneCancelOther. Placing any other number of orders will result in an error.

Order model consists of:

Name Type Description
client_order_id String Optional. Must be different from the identifiers of other orders in the list.
If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
For an allOrNone order list, symbol code must be unique for each order in the list.
For an oneTriggerOneCancelOther order list, symbol code must be the same for all orders in the list (placing orders in different order books is not supported).
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Accepted values:
for allOrNonelimit, market;
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — limit, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket;
for oneTriggerOneCancelOtherlimit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
Default value: limit
time_in_force String Optional (required for allOrNone). Time in Force instruction.
Accepted values:
for allOrNoneFOK;
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — GTC, IOC (except limit orders), FOK (except limit orders), Day, GTD;
for oneTriggerOneCancelOtherGTC, IOC, FOK, Day, GTD.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is '0').
take_rate Number Optional. Liquidity taker fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.
make_rate Number Optional. Liquidity provider fee, a fraction of order volume, such as 0.001 (for 0.1% fee). Can only increase the fee. Used for fee markup.

Cancel Spot Order

Request:

{
  "method": "spot_cancel_order",
  "params": {
    "client_order_id": "57d5525562c945448e3cbd559bd068c4"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583569472521,
    "client_order_id": "8a97337322774d8ea56448290fbc87b3",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.01",
    "post_only": false,
    "created_at": "2021-07-02T01:03:56.625Z",
    "updated_at": "2021-07-02T01:05:41.84Z",
    "report_type": "canceled"
  },
  "id": 123
}

Method: spot_cancel_order

Cancels an existing order.

Cancel/Replace Spot Order

Request:

{
  "method": "spot_replace_order",
  "params": {
    "client_order_id": "d6b645556af740b1bd1683400fd9cbce",
    "new_client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "quantity": "0.00001",
    "price": "0.02"
  },
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583572753114,
    "client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.02",
    "post_only": false,
    "created_at": "2021-07-02T01:10:06.976Z",
    "updated_at": "2021-07-02T01:11:18.238Z",
    "original_client_order_id": "d6b645556af740b1bd1683400fd9cbce",
    "report_type": "replaced"
  }
}

The Cancel/Replace request is used to change the parameters of an existing order and to change the quantity or price attribute of an open order.

Do not use this request to cancel the quantity remaining in an outstanding order. Use the Cancel request message for this purpose.

It is stipulated that a newly entered order cancels a prior order that has been entered but not yet executed.

Method: spot_replace_order

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Identifier of the order being replaced.
new_client_order_id String Optional. client_order_id for a new order. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
quantity Number New order quantity.
price Number Optional. Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
strict_validate Boolean Optional. Price and quantity will be checked for the incrementation within tick size and quantity step. See symbol's tick_size and quantity_increment.

Cancel Spot Orders

Request:

{
  "method": "spot_cancel_orders",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
  {
    "id": 583572753114,
    "client_order_id": "d6b645556af740b1bd1683400fd9cbcf",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "0.02",
    "post_only": false,
    "created_at": "2021-07-02T01:10:06.976Z",
    "updated_at": "2021-07-02T01:11:18.238Z",
    "report_type": "canceled"
  }
  ]
}

Method: spot_cancel_orders

Cancels all user's active orders and returns the ones which could not be canceled.

Requires the "Place/cancel orders" API key Access Right.

Subscribe to Spot Balances

Request

{
  "method": "spot_balance_subscribe",
  "params": {
    "mode": "updates"
  },
  "id": 123
}

Subscription result:

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

Notification Spot balance

{
  "jsonrpc": "2.0",
  "method": "spot_balance",
  "params": [
    {
      "currency": "BCN",
      "available": "100.000000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ]
}

Method: spot_balance_subscribe, spot_balance_unsubscribe

Income methods: spot_balance

Subscribes to the user's balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
mode String Subscription mode.
Accepted values:
updates — messages arrive after balance updates.
batches — messages arrive at equal intervals if there were any updates.

Response:

Name Type Description
currency String Currency code.
available Number Amount available for trading or transfer to wallet.
reserved_margin Number Amount reserved for margin trading funded by an isolated margin account.
cross_margin_reserved Number Amount reserved for margin trading funded by a cross–margin account.
reserved Number Total amount reserved for active orders and incomplete transfers to wallet.

Get Spot Trading Balances

Request:

{
  "method": "spot_balances",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": [
    {
      "currency": "BCN",
      "available": "100.000000000000",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "BTC",
      "available": "0.013634021",
      "reserved": "0",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    },
    {
      "currency": "ETH",
      "available": "0",
      "reserved": "0.00200000",
      "reserved_margin": "0",
      "cross_margin_reserved": "0"
    }
  ],
  "id": 123
}

Method: spot_balances

Returns all non-zero trading balances.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Spot Trading Balance

Request:

{
  "method": "spot_balance",
  "params": {
    "currency": "BTC"
  },
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": {
    "currency": "BTC",
    "available": "0.013634021",
    "reserved": "0",
    "reserved_margin": "0",
    "cross_margin_reserved": "0"
  },
  "id": 123
}

Method: spot_balance

Returns trading balance for a single currency.

Get Spot Fees

Request:

{
  "method": "spot_fees",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result": [
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  {
    "symbol": "ETHBTC",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  }
  ],
  "id": 123
}

Method: spot_fees

Returns fees for all available symbols.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Get Spot Fee

Request:

{
  "jsonrpc":"2.0",
  "method": "spot_fee",
  "params": {
    "symbol": "BTCUSDT"
  },
  "id": 123
}

Response:

{
  "jsonrpc":"2.0",
  "result":
  {
    "symbol": "BTCUSDT",
    "take_rate": "0.001",
    "make_rate": "-0.0001"
  },
  "id": 123
}

Method: spot_fee

Returns fees for the symbol specified.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Socket Margin Trading

Description

API provides the following tools to manage margin trading: * subscribe to the reports about: * margin account changes; * margin orders. * setup isolated margin account — reserve amount for margin trading per symbol; * handle margin orders: * list orders; * place a new order; * cancel an order; * alter an order; * cancel all orders. * close position.

Subscribe to Reports

Request

wscat -c wss://api.hitbtc.com/api/3/ws/trading
{
  "method": "margin_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

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

Notification. Margin Orders snapshot:

{
  "jsonrpc": "2.0",
  "method": "margin_orders",
  "params": [
    {
      "id": 584244931496,
      "client_order_id": "b5acd79c0a854b01b558665bcf379456",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.01",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T22:52:32.864Z",
      "updated_at": "2021-07-02T22:52:32.864Z",
      "margin_mode": "isolated",
      "report_type": "status"
    },
    {
      "id": 584246978340,
      "client_order_id": "eeb7d144eca545cd93d83078bc60b7f4",
      "symbol": "BTCUSDT",
      "side": "buy",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.01000",
      "quantity_cumulative": "0",
      "price": "0.02",
      "post_only": false,
      "reduce_only": false,
      "display_quantity": "0",
      "created_at": "2021-07-02T22:56:43.588Z",
      "updated_at": "2021-07-02T22:56:43.588Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ]
}

Notification. Margin Order update:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "display_quantity": "0",
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Margin trade:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "trade_id": 1361988214,
    "trade_quantity": "0.00001",
    "trade_price": "49509.81",
    "trade_fee": "0.001237745250",
    "trade_position_id": 485308,
    "report_type": "trade"
  }
}

Notification. Margin Accounts snapshot:

{
  "jsonrpc": "2.0",
  "method": "margin_accounts",
  "params": [
    {
      "symbol": "BTCUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "27269.85",
          "price_liquidation": "26721.57",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T00:54:28.591Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "ETHUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:20:25.118Z",
      "updated_at": "2021-07-01T21:20:25.118Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.002000000000",
          "reserved_orders": "0",
          "reserved_positions": "0"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Notification. Margin Account update:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T00:54:28.591Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0",
        "reserved_positions": "0.029630234750"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "27269.85",
        "price_liquidation": "26721.57",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T00:54:28.591Z"
      }
    ],
    "report_type": "status",
    "report_reason": "status"
  }
}

Method: margin_subscribe, margin_unsubscribe

Requires the "Orderbook, History, Trading balance" API key Access Right.

Income method: margin_order, margin_orders

Fields:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader.
symbol String Symbol code.
side String Trade side.
Accepted values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — (in updates) order quantity filled completely.
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
price Number Order price.
cum_quantity Number Cumulative executed quantity.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
display_quantity String The visible part of the hidden order quantity (the only valid value is "0").
created_at DateTime Report creation date.
updated_at DateTime Date of the report's last update.
margin_mode String Margin mode.
Possible values: isolated, cross
stop_price Number Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
expire_time DateTime Date of order expiration for time_in_force equal to GTD.
original_client_order_id String Identifier of replaced order.
trade_id Number Trade identifier. Required if report_type is trade.
trade_quantity Number Quantity of trade. Required if report_type is trade.
trade_price Number Trade price. Required if report_type is trade.
trade_fee Number Fee paid for trade. Required if report_type is trade.
trade_taker Boolean Liquidity indicator. Required if report_type is trade.
trade_position_id Number Position identifier of the trade.
report_type String Report type.
Possible values:
status — (in snapshots) the record of an event occurred during the last snapshot period.
new — (in updates) an order has been placed in the order book (status is new).
suspended — (in updates) a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book (status is suspended).
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
rejected — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the status of the related canceled/replaced order will not change — i.e., it cannot be different from new, suspended, partiallyFilled). status is rejected.
expired — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (status is expired).
replaced — (in updates) an order cancel/replace request has been accepted and successfully processed (status is canceled, a new order placed instead has the new status value).
trade — (in updates) an order has been fully or partially executed (status is filled or partiallyFilled).

Income method: margin_account, margin_accounts

Fields:

Name Type Description
symbol String Trading symbol. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., "BTCUSDT").
type String Type of margin. Only isolated.
leverage Number Optional. Margin leverage. The ratio of the trader's own funds to funds borrowed from the platform.
created_at DateTime Account creation date and time.
updated_at DateTime Account last update date and time.
currencies Currency Amount of funds on Margin Account.
positions Position Optional. Open positions of the Margin Account.
report_type String Report type.
Possible values:
status — status of margin account requested, e.g., subscription report with a list of current margin accounts.
created — new margin account created or position, e.g., new margin account requested or a flip trade occurs with position.
updated — margin account or position updated.
closed — margin account closed.
report_reason String Report reason.
Possible values: status, created, updated, marginChanged, openTrade, closeTrade, flipTrade, closed, reopened, liquidated, interestTaken, liquidationTrade

Currency model consists of:

Name Type Description
code String Currency code.
margin_balance Number The total value of funds reserved for the position.
reserved_orders Number The value reserved for active orders in the position.
reserved_positions Number The minimum value reserved for position's executed quantity that cannot be reduced.

Report type values:

Status Description
status Status of margin account requested, e.g., get accounts or subscription report with a list of current margin accounts.
created A new margin account created, e.g., new margin account has been created or recreated as a result of flip trade occurs with the position.
updated Margin account or position has been updated.
closed Margin account has been closed.

Report reason values:

Status Description
status Response to an account information request.
created Position has been created.
updated Position has been changed as a result of any order report, e.g., new, canceled, filled, and so on.
marginChanged Margin account has been changed as a result of any requested change of the margin_balance.
openTrade Opening trade has been executed.
closeTrade Closing trade has been executed.
flipTrade The position has been flipped as a result of opposite order execution with a quantity exceeding the position quantity (quantity has changed sign).
closed The position quantity has been set to "0" (zero) as a result of close trade.
liquidated The position has been liquidated.
interestTaken The interest rate has been paid.
liquidationTrade Liquidation order has been placed.

Get Margin Orders

Request:

{
  "method": "margin_get_orders",
  "params": {},
  "id": 1234
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "display_quantity": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ],
  "id": 1234
}

Method: margin_get_orders

Returns all active margin orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Place New Margin Order

Request:

{
  "method": "margin_new_order",
  "params": {
    "symbol": "BTCUSDT",
    "side": "buy",
    "quantity": "0.00001",
    "price": "30000",
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1238
}

Notification. Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0.027375000000",
        "reserved_positions": "0.049647514286"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "30218.68",
        "price_liquidation": "29611.12",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:41:07.18Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "display_quantity": "0",
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  },
  "id": 1238
}

Method: margin_new_order

Places a new margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Optional. Unique order identifier as assigned by the trader. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Must be set to market, stopMarket, or takeProfitMarket if price was left unspecified.
Accepted values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
Default value: limit
time_in_force String Optional.
Accepted values: GTC, IOC, FOK, Day, GTD
Default value:
FOKtype is market, stopMarket, takeProfitMarket;
GTCtype is limit, stopLimit, takeProfitLimit.
quantity Number Order quantity.
price Number Order price. Required for limit types.
stop_price Number Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
expire_time DateTime Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol's tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is '0').
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated

Create New Margin Order List

Request:

{
  "method": "margin_new_order_list",
  "params": {
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "orders": [
      {
        "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
        "symbol": "ETHBTC",
        "side": "buy",
        "type": "limit",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "price": "0.046016",
        "reduce_only": false,
        "display_quantity": "0",
        "post_only": false
      },
      {
        "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
        "symbol": "ETHBTC",
        "side": "sell",
        "type": "stopMarket",
        "time_in_force": "GTC",
        "quantity": "0.063",
        "stop_price": "0.044050",
        "price": "0.044016",
        "reduce_only": false,
        "display_quantity": "0",
        "post_only": false
      }
    ]
  },
  "id": 123
}

Success response:

{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450210,
    "client_order_id": "d8574207d9e3b16a4a5511753eeef175",
    "symbol": "ETHBTC",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "price": "0.046016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "display_quantity": "0",
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}
{
  "jsonrpc": "2.0",
  "result":
  {
    "id": 840450211,
    "client_order_id": "a53406ea49e160c63b620ca21e9fb634",
    "symbol": "ETHBTC",
    "side": "sell",
    "status": "suspended",
    "type": "stopMarket",
    "time_in_force": "GTC",
    "quantity": "0.063",
    "stop_price": "0.044050",
    "price": "0.044016",
    "quantity_cumulative": "0.000",
    "post_only": false,
    "reduce_only": false,
    "display_quantity": "0",
    "order_list_id": "d8574207d9e3b16a4a5511753eeef175",
    "contingency_type": "oneCancelOther",
    "created_at": "2024-04-15T17:01:05.092Z",
    "updated_at": "2024-04-15T17:01:05.092Z",
    "margin_mode": "isolated"
  }
  "id": 123
}

Example error response:

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

Method: margin_new_order_list

Creates a new margin order list.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
order_list_id String Order list identifier. If omitted, it will be generated by the system upon order list creation. Must be equal to client_order_id of the first order in the request.
contingency_type String Order list type.
Accepted values:
oneCancelOther (OCO) — all orders in the set should be canceled if one of them was executed;
oneTriggerOther (OTO) — execution of the first (primary) order on the list activates other (secondary) orders as independent of each other;
oneTriggerOneCancelOther (OTOCO) — the execution of the first (primary) order on the list activates the other (secondary) orders as an OCO order list.
orders []Order Orders in the list. There must be 2 or 3 orders for allOrNone/oneCancelOther/oneTriggerOther and 3 — for oneTriggerOneCancelOther. Placing any other number of orders will result in an error.

Order model consists of:

Name Type Description
client_order_id String Optional. Must be different from the identifiers of other orders in the list.
If omitted, it will be generated by the system upon order list creation. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
symbol String Symbol code.
Must be the same for all orders in an oneTriggerOneCancelOther order list (placing orders in different order books is not supported).
side String Trade side.
Accepted values: sell, buy
type String Optional. Order type.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — limit, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket;
for oneTriggerOneCancelOtherlimit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket.
Default value: limit
time_in_force String Optional. Time in Force instruction.
Accepted values:
for oneCancelOther (and secondary orders in oneTriggerOneCancelOther) — GTC, IOC (except limit orders), FOK (except limit orders), Day, GTD;
for oneTriggerOneCancelOtherGTC, IOC, FOK, Day, GTD.
quantity Number Order quantity.
price Number Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number The price level that triggers order activation. Required if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
expire_time DateTime Date of order expiration. Required if time_in_force is GTD.
strict_validate Boolean Price and quantity will be checked for incrementation within the symbol’s tick size and quantity step. See the symbol's tick_size and quantity_increment.
post_only Boolean Optional. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Optional. Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
Default: false
Conditions: quantity is omitted.
display_quantity String Optional. The visible part of the hidden order quantity (the only valid value is "0").
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated

Cancel Margin Order

Request:

{
  "method": "margin_cancel_order",
  "params": {
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1240
}

Notification. Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  }
}

Notification. Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080706742356",
      "reserved_orders": "0",
      "reserved_positions": "0.029822235125"
    }
    ],
    "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "margin_mode": "isolated",
      "price_entry": "33386.18",
      "price_margin_call": "27269.85",
      "price_liquidation": "26721.57",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:46:06.016Z"
    }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "canceled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:46:06.016Z",
    "margin_mode": "isolated",
    "report_type": "canceled"
  },
  "id": 1240
}

Method: margin_cancel_order

Cancels an active margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Required. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.

Cancel/Replace Margin Order

Request:

{
  "method": "margin_replace_order",
  "params": {
    "quantity": "0.00001",
    "price": "32000",
    "client_order_id": "2d42e072e4f34846954509c955303e12",
    "new_client_order_id": "2d42e072e4f34846954509c955303e13"
  },
  "id": 1239
}

Notification. Margin Order report:

{
  "jsonrpc": "2.0",
  "method": "margin_order",
  "params": {
    "id": 583593326663,
    "client_order_id": "2d42e072e4f34846954509c955303e13",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "32000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:48:21.882Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "margin_mode": "isolated",
    "original_client_order_id": "2d42e072e4f34846954509c955303e12",
    "report_type": "replaced"
  }
}

Notification. Margin Account report:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "currencies": [
    {
      "code": "USDT",
      "margin_balance": "0.080706742356",
      "reserved_orders": "0.029200000000",
      "reserved_positions": "0.030699895239"
    }
    ],
    "positions": [
    {
      "id": 485264,
      "symbol": "BTCUSDT",
      "quantity": "0.00001",
      "margin_mode": "isolated",
      "price_entry": "33386.18",
      "price_margin_call": "30415.27",
      "price_liquidation": "29803.76",
      "pnl": "0",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:49:51.003Z"
    }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583593326663,
    "client_order_id": "2d42e072e4f34846954509c955303e13",
    "symbol": "BTCUSDT",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "32000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:48:21.882Z",
    "updated_at": "2021-07-02T01:49:51.003Z",
    "margin_mode": "isolated",
    "original_client_order_id": "2d42e072e4f34846954509c955303e12",
    "report_type": "replaced"
  },
  "id": 1239
}

Method: margin_replace_order

Changes the parameters of an existing margin order.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
client_order_id String Identifier of the order being replaced.
new_client_order_id String Optional. client_order_id for a new order. Uniqueness must be guaranteed until the last order with the same client_order_id becomes inactive (canceled, expired, or fully executed) and some time after that.
quantity Number New order quantity.
price Number Optional. Order price. Required if type is limit, stopLimit, or takeProfitLimit.
stop_price Number Optional. The price level that triggers order activation. Specified if type is stopLimit, stopMarket, takeProfitLimit, or takeProfitMarket.
strict_validate Boolean Optional. Price and quantity will be checked for the incrementation within tick size and quantity step. See symbol's tick_size and quantity_increment.

Get Margin Accounts

Request:

{
  "method": "margin_get_accounts",
  "params": {},
  "id": 123
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "symbol": "ETHUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:20:25.118Z",
      "updated_at": "2021-07-01T21:20:25.118Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.002000000000",
          "reserved_orders": "0",
          "reserved_positions": "0"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "BTCUSDT",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T01:49:51.003Z",
        "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0.029200000000",
          "reserved_positions": "0.030699895239"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "30415.27",
          "price_liquidation": "29803.76",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T01:49:51.003Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Method: margin_get_accounts

Returns a list of Margin Accounts with details about open positions.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Create/Update Margin Account

Request:

{
  "method": "margin_set_account",
  "params": {
    "margin_balance": "0.07",
    "symbol": "BTCUSDT",
    "margin_mode": "isolated"
  },
  "id": 1234
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:54:46.636Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0.029200000000",
        "reserved_positions": "0.030699895239"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "31568.60",
        "price_liquidation": "30933.90",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:54:46.636Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "marginChanged"
  },
  "id": 1234
}

Notification:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:54:46.636Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0.029200000000",
        "reserved_positions": "0.030699895239"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "31568.60",
        "price_liquidation": "30933.90",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:54:46.636Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "marginChanged"
  }
}

Method: margin_set_account

Adds a margin for the specified symbol meaning creating the corresponding position of the entire margin value.

Setting margin balance to zero will lead to closing the margin account and return of all formerly reserved funds to the trading account.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Parameters:

Name Type Description
symbol String Symbol code. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., "BTCUSDT").
margin_mode String Margin mode.
Accepted values: isolated, cross
margin_balance Number Amount of currency reserved.
strict_validate Boolean The value indicating whether the margin_balance is going to be checked for correct non-exponential format and currency precision.

Close Margin Position

Request:

{
  "method": "margin_close_position",
  "params": {
    "symbol": "BTCUSDT",
    "margin_mode": "isolated"
  },
  "id": 1243
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:57:21.752Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.070000000000",
        "reserved_orders": "0",
        "reserved_positions": "0.030741868625"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT",
        "quantity": "0.00001",
        "margin_mode": "isolated"
        "price_entry": "33386.18",
        "price_margin_call": "28423.18",
        "price_liquidation": "27851.72",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:57:21.752Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  },
  "id": 1243
}

Notification:

{
  "jsonrpc": "2.0",
  "method": "margin_account",
  "params": {
    "symbol": "BTCUSDT",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:57:21.752Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.067915777250",
        "reserved_orders": "0",
        "reserved_positions": "0"
      }
    ],
    "positions": null,
    "report_type": "closed",
    "report_reason": "closed"
  }
}

Method: margin_close_position

Closes a position for the specified symbol. This will result in canceling all open orders within the position.

Requires the "Place/cancel orders" API key Access Right.

Parameters:

Name Type Description
symbol String Symbol code. Where base currency is the currency of funds reserved on the trading account for positions and quote currency is the currency of funds reserved on a margin account (e.g., "BTCUSDT").
margin_mode String Optional. Margin mode.
Accepted values: isolated, cross
Default: isolated

Socket Futures Trading

Description

API provides the following tools to manage margin trading:

Subscribe to Reports

Request

wscat -c wss://api.hitbtc.com/api/3/ws/trading
{
  "method": "futures_subscribe",
  "params": {},
  "id": 123
}

Subscription result:

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

Notification. Futures orders snapshot:

{
  "jsonrpc": "2.0",
  "method": "futures_orders",
  "params": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    },
    {
      "id": 583583708581,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01387",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "display_quantity": "0",
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ]
}

Notification. Futures order update:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT_PERP",
    "side": "sell",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Futures trade:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583583708580,
    "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
    "symbol": "BTCUSDT",
    "side": "sell",
    "status": "filled",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0.00001",
    "price": "80000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:32:15.732Z",
    "updated_at": "2021-07-02T01:32:15.732Z",
    "margin_mode": "isolated",
    "trade_id": 1361988214,
    "trade_quantity": "0.00001",
    "trade_price": "49509.81",
    "trade_fee": "0.001237745250",
    "trade_position_id": 485308,
    "report_type": "trade"
  }
}

Notification. Futures accounts snapshot:

{
  "jsonrpc": "2.0",
  "method": "futures_accounts",
  "params": [
    {
      "symbol": "BTCUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": [
        {
          "id": 485264,
          "symbol": "BTCUSDT_PERP",
          "quantity": "0.00001",
          "margin_mode": "isolated",
          "price_entry": "33386.18",
          "price_margin_call": "27269.85",
          "price_liquidation": "26721.57",
          "pnl": "0",
          "created_at": "2021-07-01T21:43:19.727Z",
          "updated_at": "2021-07-02T00:54:28.591Z"
        }
      ],
      "report_type": "status",
      "report_reason": "status"
    },
    {
      "symbol": "ETHUSDT_PERP",
      "type": "isolated",
      "leverage": "12.00",
      "created_at": "2021-07-01T21:43:19.727Z",
      "updated_at": "2021-07-02T00:54:28.591Z",
      "currencies": [
        {
          "code": "USDT",
          "margin_balance": "0.080706742356",
          "reserved_orders": "0",
          "reserved_positions": "0.029630234750"
        }
      ],
      "positions": null,
      "report_type": "status",
      "report_reason": "status"
    }
  ]
}

Method: futures_subscribe, futures_unsubscribe

Income method: futures_order, futures_orders

Requires the "Orderbook, History, Trading balance" API key Access Right.

Fields:

Name Type Description
id Number Unique order identifier as assigned by exchange.
client_order_id String Unique order identifier as assigned by the trader.
symbol String Contract code.
side String Trade side.
Accepted values: sell, buy
status String Order state.
Possible values:
new — an order is placed in the order book.
suspended — a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book.
partiallyFilled — an order is executed, but a part of its quantity is not filled yet.
filled — (in updates) order quantity filled completely.
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
expired — (in updates) an order is deactivated after it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements.
type String Order type.
Possible values: limit, market, stopLimit, stopMarket, takeProfitLimit, takeProfitMarket
time_in_force String Time in Force is a special instruction used when placing an order to indicate how long it will remain active before it is executed or expired.
GTC — "Good-Till-Canceled" order won't be closed until it is filled.
IOC — "Immediate-Or-Cancel" order must be executed immediately. Any part of an IOC order that cannot be filled immediately will be canceled.
FOK — "Fill-Or-Kill" order must be executed immediately and completely or not executed at all.
Day — keeps the order active until the end of the trading day (23:59 UTC+0).
GTD — "Good-Till-Date" order may remain active until the time specified in expire_time.
quantity Number Order quantity.
price Number Order price.
cum_quantity Number Cumulative executed quantity.
post_only Boolean A post-only order is an order that does not remove liquidity. If a post-only order causes a match with a pre-existing order as a taker, then the order will expire.
reduce_only Boolean Reduce-only order, being filled, guarantees not to put the position quantity to the point when the position flips.
close_position Boolean Flag indicating a stop market order must close a margin position when executed or be canceled otherwise.
display_quantity String The visible part of the hidden order quantity (the only valid value is "0").
created_at DateTime Report creation date.
updated_at DateTime Date of the report's last update.
margin_mode String Margin mode.
Possible values: isolated, cross
stop_price Number Required for stop-limit, stop-market, take-profit limit, and take-profit market orders.
expire_time DateTime Date of order expiration for time_in_force equal to GTD.
original_client_order_id String Identifier of replaced order.
trade_id Number Trade identifier. Required if report_type is trade.
trade_quantity Number Quantity of trade. Required if report_type is trade.
trade_price Number Trade price. Required if report_type is trade.
trade_fee Number Fee paid for trade. Required if report_type is trade.
trade_taker Boolean Liquidity indicator. Required if report_type is trade.
trade_position_id Number Position identifier of the trade.
report_type String Report type.
Possible values:
status — (in snapshots) the record of an event occurred during the last snapshot period.
new — (in updates) an order has been placed in the order book (status is new).
suspended — (in updates) a stopLimit, stopMarket, takeProfitLimit or takeProfitMarket order is parked until it meets the conditions for placement in the order book (status is suspended).
canceled — (in updates) an order is canceled. It can either be done by a user through a cancel/replace request or by the system under specific circumstances.
rejected — (in updates) order request has been rejected (it is applicable exclusively to a request entry, so the status of the related canceled/replaced order will not change — i.e., it cannot be different from new, suspended, partiallyFilled). status is rejected.
expired — (in updates) an order is deactivated as it no longer satisfies Time in Force (IOC, FOK) or Post Only requirements (status is expired).
replaced — (in updates) an order cancel/replace request has been accepted and successfully processed (status is canceled, a new order placed instead has the new status value).
trade — (in updates) an order has been fully or partially executed (status is filled or partiallyFilled).

Income method: futures_account, futures_accounts

Fields:

Name Type Description
symbol String Contract code (e.g., "BTCUSDT_PERP").
type String Type of margin. Only isolated.
leverage Number Margin leverage. The ratio of the trader's own funds to funds borrowed from the platform.
created_at DateTime Account creation date and time.
updated_at DateTime Account last update date and time.
currencies Currency Amount of funds on Margin Account.
positions Position Optional. Open positions of the Margin Account.
report_type String Report type.
Possible values:
status — status of margin account requested, e.g., subscription report with a list of current margin accounts.
created — new margin account created or position, e.g., new margin account requested or a flip trade occurs with position.
updated — margin account or position updated.
closed — margin account closed.
report_reason String Report reason. Possible values: status, created, updated, marginChanged, openTrade, closeTrade, flipTrade, closed, reopened, liquidated, liquidationTrade, interestTaken, fundingTaken, deleveraged, deleverageTrade.

Currency model consists of:

Name Type Description
code String Currency code.
margin_balance Number The total value of funds reserved for the position.
reserved_orders Number The value reserved for active orders in the position.
reserved_positions Number The minimum value reserved for position's executed quantity that cannot be reduced.

Report type values:

Status Description
status Status of futures account requested, e.g., get accounts or subscription report with a list of current futures accounts.
created A new futures account created, e.g., new futures account has been created or recreated as a result of flip trade occurs with the position.
updated Futures account or position has been updated.
closed Futures account has been closed.

Report reason values:

Status Description
status Response to an account information request.
created Position has been created.
updated Position account has been changed as a result of any order report, e.g., new, canceled, filled, and so on.
marginChanged Futures account has been changed as a result of any requested change of the margin_balance.
openTrade Opening trade has been executed.
closeTrade Closing trade has been executed.
flipTrade The position has been flipped as a result of the opposite order execution with a quantity exceeding the position quantity (quantity has changed sign).
closed The position quantity has been set to "0" (zero) as a result of the closing trade.
liquidated The position has been liquidated.
liquidationTrade Liquidation order has been placed.
fundingTaken The interest rate has been paid.
deleveraged The position has changed because of ADL activation.

Get Active Futures Orders

Notification report

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": 583583708580,
      "client_order_id": "5c8c50cbf326488cb1d3415cd3e01386",
      "symbol": "BTCUSDT_PERP",
      "side": "sell",
      "status": "new",
      "type": "limit",
      "time_in_force": "GTC",
      "quantity": "0.00001",
      "quantity_cumulative": "0",
      "price": "80000.00",
      "post_only": false,
      "reduce_only": false,
      "created_at": "2021-07-02T01:32:15.732Z",
      "updated_at": "2021-07-02T01:32:15.732Z",
      "margin_mode": "isolated",
      "report_type": "status"
    }
  ],
  "id": 1234
}

Method: futures_get_orders

Returns the user's active orders.

Requires the "Orderbook, History, Trading balance" API key Access Right.

Place New Futures Order

Request:

{
  "method": "futures_new_order",
  "params": {
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "quantity": "0.00001",
    "price": "30000",
    "client_order_id": "2d42e072e4f34846954509c955303e11"
  },
  "id": 1238
}

Notification. Futures Order report:

{
  "jsonrpc": "2.0",
  "method": "futures_order",
  "params": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC",
    "quantity": "0.00001",
    "quantity_cumulative": "0",
    "price": "30000.00",
    "post_only": false,
    "reduce_only": false,
    "created_at": "2021-07-02T01:41:07.18Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "margin_mode": "isolated",
    "report_type": "new"
  }
}

Notification. Futures Account report:

{
  "jsonrpc": "2.0",
  "method": "futures_account",
  "params": {
    "symbol": "BTCUSDT_PERP",
    "type": "isolated",
    "leverage": "12.00",
    "created_at": "2021-07-01T21:43:19.727Z",
    "updated_at": "2021-07-02T01:41:07.18Z",
    "currencies": [
      {
        "code": "USDT",
        "margin_balance": "0.080706742356",
        "reserved_orders": "0.027375000000",
        "reserved_positions": "0.049647514286"
      }
    ],
    "positions": [
      {
        "id": 485264,
        "symbol": "BTCUSDT_PERP",
        "quantity": "0.00001",
        "margin_mode": "isolated",
        "price_entry": "33386.18",
        "price_margin_call": "30218.68",
        "price_liquidation": "29611.12",
        "pnl": "0",
        "created_at": "2021-07-01T21:43:19.727Z",
        "updated_at": "2021-07-02T01:41:07.18Z"
      }
    ],
    "report_type": "updated",
    "report_reason": "updated"
  }
}

Success response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": 583588368047,
    "client_order_id": "2d42e072e4f34846954509c955303e11",
    "symbol": "BTCUSDT_PERP",
    "side": "buy",
    "status": "new",
    "type": "limit",
    "time_in_force": "GTC