Navbar
现货 币本位交割合约 币本位永续合约 U本位合约 new API
简体中文
json

Change Log

Release Time
(UTC +8)		 API New / Update Description
2022.06.24 POST /v2/sub-user/api-key-generation update Input parameter otptoken changed from required to non required.
2022.06.17 POST /v1/dw/withdraw/api/create update Please check whether the handling fee is too high through the handling fee interface before withdrawal to avoid losses, and cancel the operation through the "Cancel the Withdrawal" interface before successful withdrawal.
2022.06.14 POST /v2/sub-user/api-key-generation,
POST /v2/sub-user/api-key-modification		 Update An API key not linked with an IP address but has trading or withdrawal permissions will be automatically deactivated after 90 days of inactivity.
2022.03.02 GET v1/common/symbols,
GET /v1/settings/common/market-symbols		 Update Add response parameter: buy-limit-must-less-than，sell-limit-must-greater-than，market-sell-order-rate-must-less-than，market-buy-order-rate-must-less-than
2022.01.21 GET v1/common/symbols,
GET v1/common/currencys		 Update Add response parameter: ca-state(call auction state)
2022.01.21 GET /v2/settings/common/symbols,
GET /v1/settings/common/currencys		 Add Add "Get all Supported Trading Symbol(V2)" interface
Add "Get Currencys Settings" interface
2022.01.21 GET /v1/settings/common/symbols,
GET /v1/settings/common/market-symbols		 Add Add "Get Symbols Setting" interface
Add "Get Market Symbols Setting" interface
2022.01.21 GET /v1/settings/common/chains Add Add "Get Chains Information" interface
2022.01.08 POST /v1/order/batch-orders,
POST /v1/order/orders/place		 update Add Request Parameters "self-match-prevent"
2021.11.30 GET /v1/query/withdraw/client-order-id Add Add "Query withdrawal order by client order id"
2021.11.30 POST /v1/dw/withdraw/api/create update Add Request Parameters "client-order-id"
2021.8.19 accounts.update#${mode} Update Add "Serial Number of Account Change" parameter："seqNum"
2021.8.19 GET /v1/account/accounts/{account-id}/balance Update Add "Serial Number of Account Change" parameter："seq-num"
2021.8.12 market.$symbol.ticker Add Add Market Ticker data
2021.8.12 market.$symbol.mbp.$levels Update Add 400 depth data
2021.7.23 GET /v1/account/history Update Detailed in detail the type of change in the account flow interface, that is, "Transact-Types" increases classification, such as Note 3.
2021.6.12 GET/v2/account/valuation Add Get The Total Valuation of Platform Assets
2021.5.26 GET /v1/order/orders/getClientOrder
POST /v1/order/orders/place
POST/v1/order/orders/submitCancelClientOrder		 Update For completed orders, clientOrderId will be valid for 2 hours since the order creation (it is still valid for 8 hours concerning other orders).
The uniqueness of the clientOrderId passed in when you place an order will no longer be verified.
2021.5.12 GET /v2/etp/transactions Update "etpNames" and "transactTypes" are changed to "required" and "Only supports filling in one value"
2021.3.1 POST /v2/sub-user/deduct-mode Add Set a deduction for master and sub user
2021.3.1 GET /v2/sub-user/account-list Update Add deduct mode parameters
2021.2.28 Account and Order WebSocket v1 Delete Account and WebSocket v1 was offline
2021.2.1 POST /v2/account/repayment Update Support isolated repayment
2021.1.22 19:00 GET /v1/order/matchresults Add Add timestamp parameters
2021.1.19 19:00 GET /v2/etp/limit Add Add "Get Holding Limit of Leveraged ETP" endpoints
2020.1.8 19:00 POST/v2/algo-orders/cancel-all-after Add Add Dead man’s switch endpoints
2020.1.5 19:00 accounts.update#${mode} Update added Specify "mode" as 2:
accounts.update#2
Whenever account balance or available balance changed, it will be updated together.
2020.12.16 19:00 GET /v1/order/matchresults and GET /v1/order/orders/{order-id}/matchresults Update Add "fee-deduct-state" parameter to indicate the status of "In deduction" and "deduction completed"
2020.12.14 19:00 POST /v2/etp/{transactId}/cancel andPOST /v2/etp/batch-cancel Add Add "Submit Cancel for ETP Multiple Orders" and"Submit Cancel for an ETP Order" endpoints
2020.11.26 19:00 GET /v2/user/uid Add Add Get UID endpoints
2020.10.16 19:00 orders#${symbol} Add Add accountId for order creation event
2020.10.10 19:00 POST /v2/account/repayment,
GET /v2/account/repayment		 Add Added general repayment and query
2020.8.28 19:00 GET /v1/common/symbols Update Added API trading eligibility flag
2020.8.4 19:00 accounts.update#${mode}, accounts Update Added new event type deposit and withdraw
2020.8.11 19:00 GET /v1/common/symbols,
GET /market/etp, market.$symbol.etp,
GET /market/history/kline,
market.$symbol$.kline.$period$,
GET /v2/etp/reference,
POST /v2/etp/creation,
POST /v2/etp/redemption,
GET /v2/etp/transactions,
GET /v2/etp/transaction,
GET /v2/etp/rebalance		 Add & Update Added/updated relevant channels/endpoints to support ETP
2020.8.10 19:00 GET v1/stable-coin/quote, POST v1/stable-coin/exchange Update Added new response field for exchange fee
2020.8.4 19:00 GET /v1/account/history Update Added new response field "next-id"
2020.8.3 19:00 POST /v2/algo-orders, GET /v2/algo-orders/opening, GET /v2/algo-orders/history, GET /v2/algo-orders/specific Update Added trailing stop order
2020.7.24 19:00 trade.clearing#${symbol}#${mode} Update Added order cancellation event
2020.7.17 19:00 GET /v2/account/asset-valuation Add Add new endpoint for getting asset valuation
2020.7.16 19:00 GET /v1/common/symbols Update Add six response fields
2020.7.10 19:00 GET /v2/point/account， POST /v2/point/transfer Add Added point balance querying endpoint and point transfer endpoint
2020.7.10 19:00 POST /v1/order/batch-orders Update Adjusted rate limit value
2020.7.8 19:00 orders#{symbol} Update Added two new event types
2020.6.27 19:00 GET /v2/market-status Add Added new endpoint for market status querying
2020.6.27 19:00 market.$symbol.mbp.$levels Update Added 5-level incremental update in tick by tick mode
2020.6.27 19:00 Added some new endpoints Add Added new endpoint for conditional order
2020.6.24 19:00 GET /v1/order/orders/{order-id}/matchresults & GET /v1/order/matchresults Update Added response field 'fee-currency'
2020.6.24 19:00 GET /v2/account/withdraw/address Add Query withdraw address
2020.6.23 19:00 Added some new endpoints Add Added new endpoint for C2C lending and borrowing
2020.6.16 10:00 GET /v2/sub-user/user-list,
GET /v2/sub-user/user-state,
GET /v2/sub-user/account-list		 Add Added new endpoints for querying sub user's list, sub user's status, sub user's accounts
2020.6.15 19:00 POST /v2/sub-user/api-key-generation,
POST /v2/sub-user/api-key-modification		 Update Expand the limit of API key creation per user; Expand the limit of IP binding to each API key.
2020.6.11 19:00 POST /v1/account/transfer Update Add transfer asset between spot account and individual isolated-margin account; Add transfer asset between individual isolated-margin accounts.
2020.6.11 19:00 GET /v1/query/deposit-withdraw Update Return the reasons of the withdrawal failure
2020.6.5 19:00 POST /v2/sub-user/api-key-generation,
GET /v2/user/api-key,
POST /v2/sub-user/api-key-modification,
POST /v2/sub-user/api-key-deletion		 Add API Key management of parent user and sub users
2020.6.4 19:00 Some of private REST endpoints Update Adjusted rate limit value
2020.6.1 19:00 orders#${symbol} Update support creation event for taker's order
2020.6.1 19:00 GET /v2/reference/transact-fee-rate,
GET /v1/order/orders/{order-id}/matchresults,
GET /v1/order/matchresults,
trade.clearing#${symbol},
GET /v1/account/history, accounts,
accounts.update#${mode}		 Update Support transaction rebate
2020.5.29 19:00 POST /v2/sub-user/tradable-market Add Parent user to set sub user's trading permission
2020.5.29 19:00 POST /v2/sub-user/transferability Add Parent user to set sub user's asset transfer permission
2020.5.29 19:00 POST /v2/sub-user/creation Add Added sub user creation
2020.5.29 19:00 POST /v1/account/transfer Add Added asset Transfer endpoint
2020.4.28 11:00 market.$symbol.mbp.$levels & market.$symbol.mbp.refresh.$levels Update supported all symbols
2020.4.27 11:00 orders#${symbol} Update Changed IOC order updating behavior
2020.4.17 11:00 GET /v2/account/deposit/address, GET /v2/sub-user/deposit-address, GET /v1/query/deposit-withdraw, GET /v2/sub-user/query-deposit Add Allow sub user to deposit
2020.4.3 11:00 orders#${symbol} Add Added order update topic v2
2020.3.31 21:00 accounts.update#${mode} Update Disseminate current static values of individual accounts first just after subscription
2020.3.31 11:00 GET /v2/account/ledger Add Added account ledger query endpoint
2020.3.30 19:00 market.$symbol.mbp.refresh.$levels Add Added MBP refresh update topic
2020.3.30 19:00 POST /v1/order/orders/place,
POST /v1/order/batch-orders,
GET /v1/order/openOrders,
GET /v1/order/orders/{order-id},
GET /v1/order/orders/getClientOrder,
GET /v1/order/orders/{order-id}/matchresults,
GET /v1/order/orders,
GET /v1/order/history,
GET /v1/order/matchresults,
orders.$symbol,
trade.clearing#${symbol},
orders.$symbol.update,
orders.list		 Update Added FOK order type
2020.3.27 19:00 GET /v1/order/orders
GET /v1/order/orders		 Update Shorten the queriable period of "canceled" orders from 1 day to 2 hours.
2020.3.24 19:00 market.$symbol.mbp.$levels Update Added retrievable symbols
2020.3.17 19:00 GET /v1/order/matchresults Update The maximum value of the size field is increased from 100 to 500
2020.3.12 19:00 GET /market/tickers Update Added best bid/offer fields
2020.3.5 19:00 GET /v1/fee/fee-rate/get Delete Removed the endpoint
2020.3.2 11:00 GET https://status.huobigroup.com
/api/v2/summary.json		 New Added "Get system status" endpoint
2020.2.28 11:00 GET /v1/cross-margin/loan-orders,
GET /v1/cross-margin/accounts/balance		 Update Added new optional request parameter
2020.2.28 11:00 GET /v1/subuser/aggregate-balance,
GET /v1/account/accounts/{sub-uid}		 Update Added new enum value to account type
2020.2.28 11:00 POST /v1/cross-margin/transfer-in,
POST /v1/cross-margin/transfer-out,
GET /v1/cross-margin/loan-info,
POST /v1/cross-margin/orders,
POST /v1/cross-margin/orders/{order-id}/repay,
GET /v1/cross-margin/loan-orders,
GET /v1/cross-margin/accounts/balance		 Update Authorised sub user's access is allowed
2020.2.5 19:00 GET /v1/order/orders/{order-id},
GET /v1/order/orders/getClientOrder,
GET /v1/order/openOrders,
GET /v1/order/orders,
GET /v1/order/history		 Update Added new field "client-order-id" in response message
2020.2.5 19:00 GET /v1/order/orders Update Added new request field "start-time"/"end-time".
2020.2.3 19:00 GET /v2/reference/transact-fee-rate New Added new endpoint for transaction fee rate querying
2020.2.3 19:00 GET /v2/reference/currencies Update Added new field for base chain information
2020.2.3 19:00 GET /v1/margin/loan-info Update Added new field for actual interest rate post deduction
2020.1.10 19:00 GET /v1/cross-margin/loan-info Update Added new field for actual interest rate post deduction
2020.1.7 19:00 GET /v1/account/history Update Allowed sub user to call this endpoint
2019.12.27 19:00 POST /v2/sub-user/management New Added "Lock/Unlock Sub User" endpoint
2019.12.27 19:00 POST /v1/order/orders/batchcancel Update Support cancel based on client order id
2019.12.27 19:00 POST /v1/order/batch-orders New Added creating batch orders endpoint
2019.12.23 15:00 market.$symbol.mbp.$levels New Added MBP subscription topic
2019.12.05 11:00 trade.clearing#${symbol} & accounts.update#${mode} New Added new subscription topic for trade updates and account change updates
2019.11.22 15:00 GET /v1/order/orders
GET /v1/order/history		 Update The query time range of canceled order is shortened to the last 1 day
2019.11.13 19:00 GET /v1/margin/loan-info
GET /v1/cross-margin/loan-info		 New Added loan interest and amount query
2019.11.08 19:45 GET /v1/order/orders/{order-id}/matchresult
GET /v1/order/matchresults		 New Added response field trade-id
2019.10.18 19:00 GET /v1/account/history New Added account history querying
2019.10.12 11:00 POST /v1/dw/withdraw/api/create Update Adjusted ERC20 as default chain for USDT
2019.10.11 10:00 Cross margin related New Added cross margin trading
2019.10.09 20:00 GET /market/trade
GET /market/history/trade
market.$symbol.trade.detail		 Update Added new response field "trade id"
2019.09.25 20:00 GET /v2/account/withdraw/quota New Added withdraw quota querying
2019.09.23 15:00 POST /v1/order/orders/{order-id}/submitcancel
POST /v1/order/orders/batchcancel		 Update Optimized error message
2019.09.20 10:00 GET /v2/reference/currencies New Added querying reference information of currency and chains
2019.09.19 16:00 market.$symbol.bbo New Added best bid/offer update in tick by tick mode
2019.09.18 20:00 GET /v1/subuser/aggregate-balance
GET /v1/account/accounts/{sub-uid}
GET /v1/margin/loan-orders
GET /v1/margin/accounts/balance		 New Added sub account isolated margin trading
2019.09.16 15:00 GET /v2/account/deposit/address New Added deposit address querying
2019.09.11 17:00 GET v1/stable-coin/quote
POST v1/stable-coin/exchange		 New Added stable coin exchange
2019.09.11 16:00 N/A Delete Removed part of code demo.
2019.09.10 10:00 Order related API Except POST /v1/order/orders/submitCancelClientOrder & GET /v1/order/openOrders Update Removed order state values submitting and cancelling
2019.09.09 11:00 POST /v1/order/orders/submitCancelClientOrder Update Revised response message detail
2019.09.09 10:00 GET /v1/order/orders
GET /v1/order/matchresults		 Update Revised description of default value and value range for "start-date" and "end-date"
2019.09.02 18:00 POST /v1/order/orders/batchCancelOpenOrders Update Revised description of request field symbol
2019.09.02 16:00 "Stable Coin Exchange" related Delete Deleted "Stable Coin Exchange" relavant API
2019.08.29 21:00 Order related New Add stop-limit order classification
2019.08.21 18:00 GET /v1/order/openOrders Update Corrected query parameters
2019.08.05 18:00 orders.$symbol.update New Added new fileds "client-order-id" and "order-type"。
2019.08.02 18:00 orders.$symbol.update Update Revised the description of field "unfilled-amount"
2019.07.23 21:00 GET /v1/order/orders/{order-id}/matchresult
GET /v1/order/matchresults		 New Added transaction fee deduction details
2019.07.23 20:00 GET /v1/fee/fee-rate/get New Added transaction fee rate
2019.07.22 12:00 GET /v1/order/orders/{order-id}/matchresults
GET /v1/order/matchresults		 New Added new fields role to indicate the order was "taker" or "maker"
2019.07.11 20:00 POST /v1/order/orders/place
POST /v1/order/orders/submitCancelClientOrder
GET /v1/order/orders/getClientOrder		 Update
New		 Support client order ID。
2019.07.08 12:00 Websocket Asset and order topics Update Enhanced Websocket heartbeat and rate limit
2019.06.14 16:00 POST /v1/dw/withdraw/api/create Update support 'fast withdraw'
2019.06.17 16:00 GET /v1/stable_coin/exchange_rate
POST /v1/stable_coin/exchange		 New Support user query Stable Coin exchange rate, and perform exchange
2019.06.12 16:00 GET /v1/common/symbols Update Add more reference information of a symbol
2019.06.06 18:00 GET /v1/query/deposit-withdraw Update Ehanced the request parameters
2019.06.05 20:00 All APIs that need authentication Update Set up 3 permission for API Key: Read, Trade and Withdraw
2019.06.10 00:00 GET /v1/order/orders
GET /v1/order/matchresults		 Update Adjusted query window as 48 hours
2019.05.15 10:00 POST /v1/futures/transfer New Allow a user to tranfer fund between spot account and future contract account.
2019.04.29 19:00 GET /v1/order/history New Support historical order querying within 48 hours. With the launching of this new endpoint, the existing REST endpoint "v1/order/orders" will be kept in service. However, the new endpoint "/v1/order/history" will have better service level than the "/v1/order/orders", especially when the service loading exceeds the threshold of our system, which means in some extremely cases, "v1/order/orders" would become unavailable, but "/v1/order/history" would be kept alive. Meanwhile, Huobi is planning to have a delegated data service to support users’ demands on long-term history data. Once this new service become available, the "v1/order/orders" will be deprecated. We will keep you informed promptly once the timeline determined.
2019.04.17 10:00 GET /v1/order/orders Update Add clarification on the value range for start-date in documents
2019.04.16 10:00 GET /v1/order/openOrders Update Correct the documents error. Both account-id and symbol are required
2019.01.17 07:00 Websocket accounts Update Add subscription parameter model
Subscription does not return frozen balance of sub-user anymore
2018.07.10 11:00 GET /market/history/kline Update The size parameter value range changes from [1-1000] to [1-2000]
2018.07.06 16:00 POST /v1/order/orders/place Update Added buy-limit-maker and sell-limit-maker order types
2018.07.06 16:00 GET /v1/order/openOrders
POST /v1/order/orders/batchCancelOpenOrders		 New Added open orders query
Added batch cancel open orders
2018.07.02 16:00 ETF related New Support transfer in/out of HB10.
2018.06.20 16:00 GET /market/tickers New Added tickers query

Introduction

Welcome to Huobi API！

This is the official Huobi API document, and will be continue updating. Huobi will also publish API announcement in advance for any API change. Please subscribe to our announcements so that you can get the latest updates.

You can click Here to view the announcements. If you want to subscribe, please click "Follow" button in the top right of the page. After login and click "Follow" again, then choose the type you want to follow. After you subscribe, the button will be changed to "Following". If you don't have any account, you need to register first in the login dialog.

How to read this document

The top of the document is the navigation menu for different API business; The language button in the top right is for different languages, it supports Chinese and English right now. The main content of each API document has three parts, the left hand side is the contents, the middle part is the document body, and the right hand side is the request and response sameple.

Below is the content for Spot API document

The first part is the overview:

The second part is detail for each API. Each API category is listed in one section, and each each section has below contents:

Quick Start

Preparation

Before you use API, you need to login the website to create API Key with proper permissions. The API key is shared for all instruments in Huobi including spot, futures, swap, options.

You can manage your API Keys here.

Every user can create at most 20 API Keys, each can be applied with either permission below:

Please remember below information after creation:

SDK and Demo

SDK (Suggested)

Java | Python3 | C++ | C# | Go

Other Demos

https://github.com/huobiapi?tab=repositories

Testnet (Stopped)

The testnet has been alive for months, however the active user count is rather low and the cost is high, after considering carefully we decide to shutdown the testnet environment.

It is suggest you use live environment, which is more stable and has more liquidity.

Interface Type

There are two types of interface, you can choose the proper one according to your scenario and preferences.

REST API

REST (Representational State Transfer) is one of the most popular communication mechanism under HTTP, each URL represents a type of resource.

It is suggested to use Rest API for one-off operation, like trading and withdraw.

WebSocket API

WebSocket is a new protocol in HTML5. It is full-duplex between client and server. The connection can be established by a single handshake, and then server can push the notification to client actively.

It is suggest to use WebSocket API to get data update, like market data and order update.

Authentication

Both API has two levels of authentication:

Public API: It is for basic information and market data. It doesn't need authentication.

Private API: It is for account related operation like trading and account management. Each private API must be authenticated with API Key.

Access URLs

You can compare the network latency between two domain api.huobi.pro and api-aws.huobi.pro, and then choose the better one for you.

In general, the domain api-aws.huobi.pro is optimized for AWS client, the latency will be lower.

REST API

https://api.huobi.pro

https://api-aws.huobi.pro

Websocket Feed (market data except MBP incremental)

wss://api.huobi.pro/ws

wss://api-aws.huobi.pro/ws

Websocket Feed (market data only MBP incremental)

wss://api.huobi.pro/feed

wss://api-aws.huobi.pro/feed

Websocket Feed (account and order)

wss://api.huobi.pro/ws/v2

wss://api-aws.huobi.pro/ws/v2

Authentication

Overview

The API request may be tampered during internet, therefore all private API must be signed by your API Key (Secrete Key).

Each API Key has permission property, please check the API permission, and make sure your API key has proper permission.

A valid request consists of below parts:

Signature Method

The signature may be different if the request text is different, therefore the request should be normalized before signing. Below signing steps take the order query as an example:

This is a full URL to query one order:

https://api.huobi.pro/v1/order/orders?

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

&SignatureMethod=HmacSHA256

&SignatureVersion=2

&Timestamp=2017-05-11T15:19:30

&order-id=1234567890

1. The request Method (GET or POST, WebSocket use GET), append line break "\n"

GET\n

2. The host with lower case, append line break "\n"

Example: api.huobi.pro\n

3. The path, append line break "\n"

For example, query orders:

/v1/order/orders\n

For example, WebSocket v2

/ws/v2

4. The parameters are URL encoded, and ordered based on ASCII

For example below is the original parameters:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

order-id=1234567890

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

Then above parameter should be ordered like below:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

order-id=1234567890

5. Use char "&" to concatenate all parameters

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&order-id=1234567890

6. Assemble the pre-signed text

GET\n

api.huobi.pro\n

/v1/order/orders\n

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&order-id=1234567890

7. Use the pre-signed text and your Secret Key to generate a signature

4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=

8. Put the signature into request URL

For Rest interface:

  1. Put all the parameters in the URL
  2. Encode signature by URL encoding and append in the URL with parameter name "Signature".

Finally, the request sent to API should be:

https://api.huobi.pro/v1/order/orders?AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&order-id=1234567890&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&Signature=4F65x5A2bLyMWVQj3Aqp%2BB4w%2BivaA7n5Oi2SuYtCJ9o%3D

For WebSocket interface:

  1. Fill the value according to required JSON schema
  2. The value in JSON doesn't require URL encode

For example:

{ "action": "req", "ch": "auth", "params": { "authType":"api", "accessKey": "e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx", "signatureMethod": "HmacSHA256", "signatureVersion": "2.1", "timestamp": "2019-09-01T18:16:16", "signature": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=" } }

Sub User

Sub user can be used to isolate the assets and trade, the assets can be transferred between parent and sub users. Sub user can only trade with the sub user. The assets can not be transferred between sub users, only parent user has the transfer permission.

Sub user has independent login password and API Key, they are managed under parent user in website.

Each parent user can create 200 sub user, each sub user can create at most 5 API Key, each API key can have two permissions: read and trade.

The sub user API Key can also bind IP address, the expiry policy is the same with parent user.

You can access here to create and manage sub user.

The sub user can access all public API (including basic information and market data), below are the private APIs that sub user can access:

API Description
POST /v1/order/orders/place Create and execute an order
POST /v1/order/orders/{order-id}/submitcancel Cancel an order
POST /v1/order/orders/submitCancelClientOrder Cancel an Order based on client order ID
POST /v1/order/orders/batchcancel Cancel multiple orders
POST /v1/order/orders/batchCancelOpenOrders Cancel the open orders
GET /v1/order/orders/{order-id} Query a specific order
GET /v1/order/orders Query orders with criteria
GET /v1/order/openOrders Query open orders
GET /v1/order/matchresults Query the order matching result
GET /v1/order/orders/{order-id}/matchresults Query a specific order matching result
GET /v1/account/accounts Query all accounts in current user
GET /v1/account/accounts/{account-id}/balance Query the specific account balance
POST /v1/futures/transfer Transfer with future account
POST /v1/dw/transfer-in/margin Transfer from spot to margin account
POST /v1/dw/transfer-out/margin Transfer from margin to spot account
POST /v1/margin/orders Request margin loan
POST /v1/margin/orders/{order-id}/repay Repay the debit for specific order
GET /v1/margin/loan-orders Query history loan orders
GET /v1/margin/accounts/balance Query margin account balance
GET /v1/account/history Query account history
POST /v1/cross-margin/transfer-in Transfer Asset from Spot Trading Account to Cross Margin Account
POST /v1/cross-margin/transfer-out Transfer Asset from Cross Margin Account to Spot Trading Account
GET /v1/cross-margin/loan-info Get Loan Interest Rate and Quota
POST /v1/cross-margin/orders Request a Margin Loan
POST /v1/cross-margin/orders/{order-id}/repay Repay Margin Loan
GET /v1/cross-margin/loan-orders Search Past Margin Orders
GET /v1/cross-margin/accounts/balance Get the Balance of the Margin Loan Account
GET /v2/account/ledger Query account ledger
POST /v1/account/transfer Asset Transfer
GET /v2/point/account Query Point Balance
POST /v2/point/transfer Point Transfer
GET /v2/etp/reference Get reference data of ETP
POST /v2/etp/creation ETP Creation
POST /v2/etp/redemption ETP Redemption
GET /v2/etp/transactions Get ETP Creation & Redemption History
GET /v2/etp/transaction Get Specific ETP Creation or Redemption Record
GET /v2/etp/rebalance Get Position Rebalance History

Glossary

Trading symbols

The trading symbols are consist of base currency and quote currency. Take the symbol BTC/USDT as an example, BTC is the base currency, and USDT is the quote currency.

Account

The account-id defines the Identity for different business type, it can be retrieved from API /v1/account/accounts , where the account-type is the business types. The types include:

You can refer to Huobi Course to get detailed information

API Access

Overview

Category URL Path Description
Common /v1/common/* Common interface, including currency, currency pair, timestamp, etc
Market Data /market/* Market data interface, including trading, depth, quotation, etc
Account /v1/account/* /v1/subuser/* Account interface, including account information, sub-user ,etc
Order /v1/order/* Order interface, including order creation, cancellation, query, etc
Margin /v1/margin/* Margin interface, including debit, payment, query, etc
Cross Margin /v1/cross-margin/* Cross margin interface, including debit, payment, query, etc

Above is a general category, it doesn't cover all API, you can refer to detailed API document according to your requirement.

New Version Rate limit Rule

Request Format

The API is restful and there are two method: GET and POST.

Response Format

The response is JSON format.There are four fields in the top level: status, ch, ts and data. The first three fields indicate the general status, the business data is is under data field.

Below is an example of response:

{
  "status": "ok",
  "ch": "market.btcusdt.kline.1day",
  "ts": 1499223904680,
  "data": // per API response data in nested JSON object
}
Field Data Type Description
status string Status of API response
ch string The data stream. It may be empty as some API doesn't have data stream
ts int The UTC timestamp when API respond, the unit is millisecond
data object The body data in response

Data Type

The JSON data type described in this document is defined as below:

Best Practice

Security

General

API Access

New Version Rate limit Rule

Market

Market data

Latest trade

Depth

Order

Place an order (/v1/order/orders/place)

Search history olders (/v1/order/orders)

Order update

Account

Asset update

API Explorer

API Explorer allows user to invoke and observe each API request and response without writing any program. The UI is designed as the same as document, which has input parameters and response description, user can use it easily without any additional user guide.

This Explorer encapsulates a shared API Key, and will show the signature calcuation steps and request parameters when it invokes API. If you encounter signature problem, you can copy the API Key and timestamp to your program and compare with the result in Explorer.

Frequently Asked Questions

This section lists the frequently asked questions regardless the specific API, such as network, signature or common errors.

For specific API question, please check the Error Code and FAQ in each API category.

Q1：What is UID and account-id?

UID is the unique ID for a user (including master user and sub user), it can be found in Web or App personal information part, or retrieved from API GET /v2/user/uid.

The account-id defines the identity for different account type under one user, it can be retrieved from API /v1/account/accounts , where the account-type is the account types.

The types include but not limited to below types, contract account types (futures/swap/option) are not included:

Q2：How many API Keys one user can apply?

Every user can create 20 API Keys, and each API Key can be granted with 3 permissions: read, trade and withdraw.

Each user could create up to 200 sub users, and each sub user could create 20 API Keys, each API key can be granted with 2 permissions: read and trade.

Below are the explanation for permissions:

  1. Read permission: It is used to query data, for example, query orders, query trades.
  2. Trade permission: it is used to place order, cancel order and transfer.
  3. Withdraw permission: it is used to withdraw, cancel withdraw.

Q3：Why APIs are always disconnected or timeout?

Please follow below suggestions:

  1. It is unstable if the client's server locates in China mainland, it is suggested to invoke API from a server at AWS Japan.
  2. It is suggested to invoke API only to host api.huobi.pro or api-was.huobi.pro.

Q4：Why the WebSocket is often disconnected?

Please check below possible reasons:

  1. The client didn't respond 'Pong'. It is requird to respond 'Pong' after receive 'Ping' from server.
  2. The server didn't receive 'Pong' successfully due to network issue.
  3. The connection is broken due to network issue.
  4. It is suggested to implement WebSocket re-connect mechanism. If Ping/Pong works well but the connection is broken, the application should be able to re-connect automatically.

Q5：What is the difference between api.huobi.pro and api-aws.huobi.pro?

The host api-aws.huobi.pro is optimized for AWS client, the latency is lower.

Q6：Why the signature authentication always fail?

Please check whether you follow below rules:

1.The parameter in signature text should be ordered by ASCII, for example below is the original parameters:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

order-id=1234567890

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

They should be ordered like below:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

order-id=1234567890

2.The signature text should be URL encoded, for example

3.The signature should be base64 encoded.

4.The parameter for Get request should be included in signature request.

5.The Timestamp should be UTC time and the format should be YYYY-MM-DDTHH:mm:ss.

6.The time difference between your timestamp and standard should be less than 1 minute.

7.The message body doesn't need URL encoded if you are using WebSocket for authentication.

8.The host in signature text should be the same as the host in your API request.

The proxy may change the request host, you can try without proxy;

Some http/websocket library may include port in the host, you can try to append port in signature host, like "api.huobi.pro:443"

9.The hidden text in API Key and Secret Key may have impact on the signature.

10.Check the byte[] is directly to be Base64 encoded after generated from the HmacSHA256 signature, instead of hexadecimal string to be Base64 encoded.

Right now the official SDK supports multiple languages, you can refer to the signature implementation, or below three signature examples.

JAVA signature example | C++ signature example | Python signature example

Q7：Why the API return 'Incorrect Access Key'?

Please check whether Access Key is wrong in URL request, such as:

  1. The AccessKeyId is not included in URL parameter
  2. The length of AccessKey is wrong
  3. The AccessKey is already deleted
  4. The URL request is not assembled correctly which cause AccessKey is parsed unexpected in server side.

Q8：Why the API return 'gateway-internal-error'?

Please check below possible reasons:

  1. It may be due to network issue or server internal error, please try again later.
  2. The data format should be correct (standard JSON).
  3. The Content-Type in POST header should be application/json .

Q9：Why the API return 'login-required'?

Please check below possible reasons:

  1. The URL request parameter should include AccessKeyId.
  2. The URL request parameter should include Signature.

Q10: Why the API return HTTP 405 'method-not-allowed'?

It indicates the request path doesn't exist, please check the path spelling carefully. Due to the Nginx setting, the request path is case sensitive, please follow the path definition in document.

Contact Us

Market Maker Program

It is very welcome for market maker who has good market making strategy and large trading volume. If your Huobi Spot account or Contract account has at least 10 BTC, you can send your email to:

And provide below details:

  1. UID (not linked to any rebate program in any accounts)
  2. Screenshot of trading volume in other transaction platform (such as trading volume within 30 days, or VIP status)
  3. A brief description of your market-making strategy

Technical Support

If you have any other questions on API, you can contact us by below ways:

If you encounter API errors, please use below template in your feedback:

1. Problem description
2. UID, Account Id and Order Id (if related with account and order)
3. Raw URL request
4. Raw JSON request (if any)
5. Raw JSON response
6. Problem time and frequency (such as, when this problem occurs, whether it is reproducible)
7. Pre-signed text (Required for authentication issue)

Below is an example：

1. Problem description: API authentication error
2. UID：123456
3. Raw URL request: https://api.huobi.pro/v1/account/accounts?&SignatureVersion=2&SignatureMethod=HmacSHA256&Timestamp=2019-11-06T03%3A25%3A39&AccessKeyId=rfhxxxxx-950000847-boooooo3-432c0&Signature=HhJwApXKpaLPewiYLczwfLkoTPnFPHgyF61iq0iTFF8%3D
4. Raw JSON request: N/A
5. Raw JSON response：{"status":"error","err-code":"api-signature-not-valid","err-msg":"Signature not valid: Incorrect Access key [Access key错误]","data":null}
6. Problem time and frequency: It occurs every time
7. Pre-signed text:
GET\n
api.huobi.pro\n
/v1/account/accounts\n
AccessKeyId=rfhxxxxx-950000847-boooooo3-432c0&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2019-11-06T03%3A26%3A13

Note：It is safe to share your Access Key, which is to prove your identity, and it will not affect your account safety. Remember do not share your Secret Key to any one. If you expose your Secret Key by accident, please remove the related API Key immediately.

Reference Data

Introduction

Reference data APIs provide public reference information such as system status, market status, symbol info, currency info, chain info and server timestamp.

Get system status

This endpoint allows users to get system status, Incidents and planned maintenance.

The system status can also be obtained through email, SMS, webhook, RSS/Atom feed. Users can click here to subscribe. The subscription function depends on Google services. Before you subscribe, please ensure that you can access Google services normally. 

curl "https://status.huobigroup.com/api/v2/summary.json"

HTTP Request

Request Parameters

No parameter is available for this endpoint.

Response:

{
  "page": {  // Basic information of huobi spot status page
    "id": "p0qjfl24znv5",  // page id
    "name": "Huobi",  // page name
    "url": "https://status.huobigroup.com", // page url
    "time_zone": "Etc/UTC", // time zone
    "updated_at": "2020-02-07T10:25:14.717Z" // page update time
  },
  "components": [  // System components and their status
    {
      "id": "h028tnzw1n5l",  // component id
      "name": "Deposit", // component name
      "status": "operational", // component status
      "created_at": "2019-12-05T02:07:12.372Z",  // component create time
      "updated_at": "2020-02-07T09:27:15.563Z", // component update time
      "position": 1,
      "description": null,
      "showcase": true,
      "group_id": "gtd0nyr3pf0k",  
      "page_id": "p0qjfl24znv5", 
      "group": false,
      "only_show_if_degraded": false
    }
  ],
  "incidents": [ // System fault incidents and their status
        {
            "id": "rclfxz2g21ly",  // incident id
            "name": "Market data is delayed",  // incident name
            "status": "investigating",  // incident status
            "created_at": "2020-02-11T03:15:01.913Z",  // incident created time
            "updated_at": "2020-02-11T03:15:02.003Z",   // incident updated time
            "monitoring_at": null,
            "resolved_at": null,
            "impact": "minor",  // incident impact
            "shortlink": "http://stspg.io/pkvbwp8jppf9",
            "started_at": "2020-02-11T03:15:01.906Z",
            "page_id": "p0qjfl24znv5",
            "incident_updates": [ 
                {
                    "id": "dwfsk5ttyvtb",   
                    "status": "investigating",   
                    "body": "Market data is delayed", 
                    "incident_id": "rclfxz2g21ly",   
                    "created_at": "2020-02-11T03:15:02.000Z",    
                    "updated_at": "2020-02-11T03:15:02.000Z",  
                    "display_at": "2020-02-11T03:15:02.000Z",   
                    "affected_components": [  
                        {
                            "code": "nctwm9tghxh6",  
                            "name": "Market data",  
                            "old_status": "operational",  
                            "new_status": "degraded_performance"  
                        }
                    ],
                    "deliver_notifications": true,
                    "custom_tweet": null,
                    "tweet_id": null
                }
            ],
            "components": [  
                {
                    "id": "nctwm9tghxh6",   
                    "name": "Market data",  
                    "status": "degraded_performance", 
                    "created_at": "2020-01-13T09:34:48.284Z", 
                    "updated_at": "2020-02-11T03:15:01.951Z", 
                    "position": 8,
                    "description": null,
                    "showcase": false,
                    "group_id": null,
                    "page_id": "p0qjfl24znv5",
                    "group": false,
                    "only_show_if_degraded": false
                }
            ]
        }
    ],
      "scheduled_maintenances": [  // System scheduled maintenance events and their status
        {
            "id": "k7g299zl765l", // incident id
            "name": "Schedule maintenance", // incident name
            "status": "scheduled", // incident status
            "created_at": "2020-02-11T03:16:31.481Z",  // incident create time
            "updated_at": "2020-02-11T03:16:31.530Z",  // incident update time
            "monitoring_at": null,
            "resolved_at": null,
            "impact": "maintenance",  // incident impact
            "shortlink": "http://stspg.io/md4t4ym7nytd",
            "started_at": "2020-02-11T03:16:31.474Z",
            "page_id": "p0qjfl24znv5",
            "incident_updates": [  
                {
                    "id": "8whgr3rlbld8",  
                    "status": "scheduled", 
                    "body": "We will be undergoing scheduled maintenance during this time.", 
                    "incident_id": "k7g299zl765l",  
                    "created_at": "2020-02-11T03:16:31.527Z",  
                    "updated_at": "2020-02-11T03:16:31.527Z",  
                    "display_at": "2020-02-11T03:16:31.527Z",  
                    "affected_components": [  
                        {
                            "code": "h028tnzw1n5l",  
                            "name": "Deposit And Withdraw - Deposit",  
                            "old_status": "operational",  
                            "new_status": "operational" 
                        }
                    ],
                    "deliver_notifications": true,
                    "custom_tweet": null,
                    "tweet_id": null
                }
            ],
            "components": [  
                {
                    "id": "h028tnzw1n5l",  
                    "name": "Deposit", 
                    "status": "operational", 
                    "created_at": "2019-12-05T02:07:12.372Z",  
                    "updated_at": "2020-02-10T12:34:52.970Z",  
                    "position": 1,
                    "description": null,
                    "showcase": false,
                    "group_id": "gtd0nyr3pf0k",
                    "page_id": "p0qjfl24znv5",
                    "group": false,
                    "only_show_if_degraded": false
                }
            ],
            "scheduled_for": "2020-02-15T00:00:00.000Z",  // scheduled maintenance start time
            "scheduled_until": "2020-02-15T01:00:00.000Z"  // scheduled maintenance end time
        }
    ],
    "status": {  // The overall current status of the system
        "indicator": "minor",   // system indicator
        "description": "Partially Degraded Service"  // system description
    }
}

Response Content

Field Data Type Description
page basic information of huobi spot status page
{id string page id
name string page name
url string page url
time_zone string time zone
updated_at} string page update time
components System components and their status
[{id string component id
name string component name, including Order submission, Order cancellation, Deposit etc.
status string component status, value range: operational, degraded_performance, partial_outage, major_outage, under maintenance
created_at string component created time
updated_at string component updated time
.......}] for details of other fields, please refer to the return example
incidents System fault incident and their status. If there is no fault at present, it will return to null
[{id string incident id
name string incident name
status string incident status, value range: investigating, identified, monitoring, resolved
created_at string incident creat time
updated_at string incident update time
.......}] for details of other fields, please refer to the return example
scheduled_maintenances System scheduled maintenance incident and status. If there is no scheduled maintenance at present, it will return to null
[{id string incident id
name string incident name
status string incident staus, value range: scheduled, in progress, verifying, completed
created_at string incident created time
updated_at string incident updated time
scheduled_for string scheduled maintenance start time
scheduled_until string scheduled maintenance end time
.......}] for details of other fields, please refer to the return example
status The overall current status of the system
{indicator string system indicator, value range: none, minor, major, critical, maintenance
description} string system description, value range: All Systems Operational, Minor Service Outager, Partial System Outage, Partially Degraded Service, Service Under Maintenance

Get Market Status

The endpoint returns current market status
The enum values of market status includes: 1 - normal (order submission & cancellation are allowed)，2 - halted (order submission & cancellation are prohibited)，3 - cancel-only(order submission is prohibited but order cancellation is allowed).
Halt reason includes: 2 - emergency maintenance，3 - schedule maintenance.

curl "https://api.huobi.pro/v2/market-status"

HTTP Request

Request Parameter

None.

Responds:

{
    "code": 200,
    "message": "success",
    "data": {
        "marketStatus": 1
    }
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE
marketStatus integer TRUE Market status (1=normal, 2=halted, 3=cancel-only)
haltStartTime long FALSE Halt start time (unix time in millisecond) , only valid for marketStatus=halted or cancel-only
haltEndTime long FALSE Estimated halt end time (unix time in millisecond) , only valid for marketStatus=halted or cancel-only; if this field is not returned during marketStatus=halted or cancel-only, it implicates the halt end time cannot be estimated at this time.
haltReason integer FALSE Halt reason (2=emergency-maintenance, 3=scheduled-maintenance) , only valid for marketStatus=halted or cancel-only
affectedSymbols string FALSE Affected symbols, separated by comma. If affect all symbols just respond with value ‘all’. Only valid for marketStatus=halted or cancel-only
</data>

Get all Supported Trading Symbol(V2)

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
ts long false timestamp to get incremental data

Note

response

{
    "status":"ok",
    "data":[
        {
            "tags": "",
            "state": "online",
            "wr": "1.5",
            "sc": "ethusdt",
            "p": [
                {
                    "id": 9,
                    "name": "Grayscale",
                    "weight": 91
                }
            ],
            "bcdn": "ETH",
            "qcdn": "USDT",
            "elr": null,
            "tpp": 2,
            "tap": 4,
            "fp": 8,
            "smlr": null,
            "flr": null,
            "whe": false,
            "cd": false,
            "te": true,
            "sp": "main",
            "d": null,
            "bc": "eth",
            "qc": "usdt",
            "toa": 1514779200000,
            "ttp": 8,
            "w": 999400000,
            "lr": 5,
            "dn": "ETH/USDT"
        }
    ],
    "ts":"1641870869718",
    "full":1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
sc symbol_code string symbol(outside)
dn display_name string display name
si state_isolated string Leverage status of symbol：online，offline
scr state_cross string Full leverage status of symbol ：online，offline
bc base_currency string base currency
bcdn base_currency_display_name string base currency display name
qc quote_currency string quote currency
qcdn quote_currency_display_name string quote currency display name
state state string symbol status. unknown，not-online，pre-online，online，suspend，offline，transfer-board，fuse
whe white_enabled boolean white enabled
cd country_disabled boolean country disabled
te trade_enabled boolean trade enabled
toa trade_open_at long the time trade open at
sp symbol_partition string symbol partition
w weight int weight sort
ttp trade_total_precision decimal(10,6) trade total precision
tap trade_amount_precision decimal(10,6) trade amount precision
tpp trade_price_precision decimal(10,6) trade price precision
fp fee_precision decimal(10,6) fee precision
suspend_desc suspend_desc string suspend desc
transfer_board_desc transfer_board_desc string transfer board desc
tags tags string Tags, multiple tags are separated by commas, such as: st, hadax
lr leverage_ratio decimal leverage ratio, such as: 3.5, or null if the symbol does not support this leverage ratio
smlr super_margin_leverage_ratio decimal super-margin leverage ratio, such as: 3, or null if the symbol does not support super-margin
flr funding_leverage_ratio String C2C leverage ratio, such as:3, or null if the symbol does not support C2C
wr withdraw_risk string withdraw_risk, such as: 3, or null if the symbol does not support super-margin
d direction int direction: 1 for long and 2 for short
elr etp_leverage_ratio string etp leverage ratio
p partitions Object
castate ca state string not Required. The state of the call auction; it will only be displayed when it is in the 1st and 2nd stage of the call auction. Enumeration values: "ca_1", "ca_2"
ca1oa ca1 open at long not Required. this information is only available for that symbols configured with call auction. The total number of milliseconds since 0:0:0:00,000 on January 1, 1970 UTC to the present.
ca2oa ca2 open at long not Required. this information is only available for that symbols configured with call auction. The total number of milliseconds since 0:0:0:00,000 on January 1, 1970 UTC to the present.
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err_code err_code string error code(returned when the interface reports an error)
err_msg err_msg string error msg(returned when the interface reports an error)

Get all Supported Currencies(V2)

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
ts long false timestamp to get incremental data

Note

response

{
    "status":"ok",
    "data":[
        {
            "tags":"",
            "cawt":false,
            "fc":12,
            "sc":12,
            "dma":"1",
            "wma":"10",
            "ft":"eth",
            "whe":false,
            "cd":false,
            "qc":true,
            "sp":"8",
            "wp":6,
            "fn":"Tether USDT",
            "at":1,
            "cc":"usdt",
            "v":true,
            "de":true,
            "wed":true,
            "w":10006,
            "state":"online",
            "dn":"USDT",
            "dd":"Please don’t deposit any other digital assets except USDT to the above address. Otherwise, you may lose your assets permanently. !>_<!Depositing to the above address requires confirmations of the entire network. It will arrive after 12 confirmations, and it will be available to withdraw after 12 confirmations. !>_<!Minimum deposit amount: 1 USDT. Any deposits less than the minimum will not be credited or refunded.!>_<!Your deposit address won’t change often. If there are any changes, we will notify you via announcement or email.!>_<!Please make sure that your computer and browser are secure and your information is protected from being tampered or leaked.",
            "svd":null,
            "swd":null,
            "sdd":null,
            "wd":"Minimum withdrawal amount: 10 USDT (ERC20). !>_<!To ensure the safety of your funds, your withdrawal request will be manually reviewed if your security strategy or password is changed. Please wait for phone calls or emails from our staff.!>_<!Please make sure that your computer and browser are secure and your information is protected from being tampered or leaked."
        }
    ],
    "ts":"1641869938436",
    "full":1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
cc currency_code string currency code
dn display_name string currency display name
fn full-name string currency full name
at asset_type int asset type, 1 virtual currency 2 fiat currency
wp withdraw_precision int withdraw precision
ft fee_type string fee type, eth: Fixed fee, btc: Interval fee husd: Fee charged in proportion
dma deposit_min_amount string deposit min amount
wma withdraw_min_amount string withdraw min amount
sp show_precision string show precision
w weight string weight
qc quote_currency boolean be quote currency
state state string symbol state. unkown, not-online, online, offline
v visible boolean visible or not -- users who have offline currency but have assets can see it
whe white_enabled boolean white enabled
cd country_disabled boolean country disabled--users who have country disabled currency but have assets can see it
de deposit_enabled boolean deposit enabled
wed withdraw_enabled boolean withdraw enabled
cawt currency_addr_with_tag boolean currency addr with tag
fc fast_confirms int fast confirms
sc safe_confirms int safe confirms
swd suspend_withdraw_desc string suspend withdraw desc
wd withdraw_desc string withdraw desc
sdd suspend_deposit_desc string suspend deposit desc
dd deposit_desc string deposit desc
svd suspend_visible_desc string suspend visible desc
tags tags string Tags, multiple tags are separated by commas, such as: st, hadax
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err_code err_code string error code(returned when the interface reports an error)
err_msg err_msg string error msg(returned when the interface reports an error)

Get Currencys Settings

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
ts long false timestamp to get incremental data

Note

response

{
    "status":"ok",
    "data":[
        {
            "tags":"",
            "name":"usdt",
            "state":"online",
            "cawt":false,
            "fc":12,
            "sc":12,
            "sp":"8",
            "iqc":true,
            "ct":"eth",
            "de":true,
            "we":true,
            "cd":false,
            "oe":1,
            "v":true,
            "whe":false,
            "wet":1609430400000,
            "det":1609430400000,
            "cp":"all",
            "vat":1508839200000,
            "ss":[
                "INSTITUTION",
                "MINEPOOL",
                "OTC"
            ],
            "fn":"Tether USDT",
            "wp":6,
            "w":10006,
            "dma":"1",
            "wma":"10",
            "dn":"USDT",
            "dd":"Please don’t deposit any other digital assets except USDT to the above address. Otherwise, you may lose your assets permanently. !>_<!Depositing to the above address requires confirmations of the entire network. It will arrive after 12 confirmations, and it will be available to withdraw after 12 confirmations. !>_<!Minimum deposit amount: 1 USDT. Any deposits less than the minimum will not be credited or refunded.!>_<!Your deposit address won’t change often. If there are any changes, we will notify you via announcement or email.!>_<!Please make sure that your computer and browser are secure and your information is protected from being tampered or leaked.",
            "svd":null,
            "swd":null,
            "sdd":null,
            "wd":"Minimum withdrawal amount: 10 USDT (ERC20). !>_<!To ensure the safety of your funds, your withdrawal request will be manually reviewed if your security strategy or password is changed. Please wait for phone calls or emails from our staff.!>_<!Please make sure that your computer and browser are secure and your information is protected from being tampered or leaked."
        }
    ],
    "ts":"1641872721891",
    "full":1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
name name string currency name
dn display-name string currency display name
vat visible-assets-timestamp long visible assets timestamp
det deposit-enable-timestamp long deposit enable timestamp
wet withdraw-enable-timestamp long withdraw enable timestamp
wp withdraw-precision int withdraw precision
ct currency-type string currency type
cp currency-partition string currency partition. INVALID, all(PRO and HADAX), pro, hadax
ss support-sites array support sites. unknown, spot, otc, futures(coin-m futures), minepool( not supports mulan), institution, swap(coin-m swap), asset(mulan does not support transfer, it is only used for reconciliation, cfd(cfd contract in Japan), chat(Huobi Chat IM), option, linear-swap(usdt-m), custody(funding account in HK), turbine, margin, super-margin
oe otc-enable integer 0: disable, 1: enable
dma deposit-min-amount string deposit min amount
wma withdraw-min-amount string withdraw min amount
sp show-precision string show precision
w weight string weight
qc quote-currency boolean be quote currency
state state string currency state. unkown, not-online, online, offline
v visible boolean visible
whe white-enabled boolean white enabled
cd country-disabled boolean country disabled
de deposit-enabled boolean deposit enabled
we withdraw-enabled boolean withdraw enabled
cawt currency-addr-with-tag boolean currency addr with tag
cao currency-addr-oneoff boolean currency addr oneoff
fc fast-confirms int fast confirms
sc safe-confirms int safe confirms
swd suspend-withdraw-desc string suspend withdraw desc
wd withdraw-desc string withdraw desc
sdd suspend-deposit-desc string suspend deposit desc
dd deposit-desc string deposit desc
svd suspend-visible-desc string suspend visible desc
tags tags string Tags, multiple tags are separated by commas, such as: st, hadax
fn full-name string currency full name
bc block-chains
iqc is-quote-currency
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err-code err-code string error code(returned when the interface reports an error)
err-msg err-msg string error msg(returned when the interface reports an error)

Get Symbols Setting

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
ts long false timestamp to get incremental data

Note

response

{
    "status":"ok",
    "data":[
        {
            "symbol":"agldusdt",
            "tags":"",
            "state":"online",
            "bcdn":"AGLD",
            "qcdn":"USDT",
            "elr":null,
            "tm":"PRO",
            "sn":"AGLD/USDT",
            "ve":true,
            "dl":false,
            "te":true,
            "ce":true,
            "cd":false,
            "tet":1630668600000,
            "we":false,
            "toa":1630668600000,
            "tca":1893470400000,
            "voa":1630666800000,
            "vca":1893470400000,
            "bc":"agld",
            "qc":"usdt",
            "sp":"innovation",
            "d":null,
            "tpp":4,
            "tap":4,
            "fp":8,
            "w":950000000,
            "ttp":8
        }
    ],
    "ts":"1641880066563",
    "full":1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
symbol symbol string symbol(outside)
sn symbol-name string symbol name
bc base-currency string base currency
qc quote-currency string quote currency
state state string symbol status. unknown，not-online，pre-online，online，suspend，offline，transfer-board，fuse
ve visible-enabled boolean visible
we white-enabled boolean white enabled
dl delist boolean delist
cd country-disabled boolean country disabled
te trade-enabled boolean trade enabled
ce cancel-enabled boolean cancel enabled
tet trade-enable-timestamp long trade enable timestamp
toa trade-open-at long the time trade open at
tca trade-close-at long the time trade close at
voa visible-open-at long visible open at
vca visible-close-at long visible close at
sp symbol-partition string symbol partition
tm trade-market string symbol partition
w weight int weight sort
ttp trade-total-precision decimal(10,6) trade total precision
tap trade-amount-precision decimal(10,6) trade amount precision
tpp trade-price-precision decimal(10,6) trade price precision
fp fee-precision decimal(10,6) fee precision
tags tags string Tags, multiple tags are separated by commas, such as: st, hadax
d direction
bcdn base_currency_display_name string base currency display name
qcdn quote_currency_display_name string quote currency display name
elr etp_leverage_ratio string etp leverage ratio
castate ca state string Not required. The state of the call auction; it will only be displayed when it is in the 1st and 2nd stage of the call auction. Enumeration values: "ca_1", "ca_2"
ca1oa ca1 open at long not Required. the open time of call auction phase 1, total milliseconds since January 1, 1970 0:0:0:00ms UTC
ca1ca ca1 close at long not Required. the close time of call auction phase 1, total milliseconds since January 1, 1970 0:0:0:00ms UTC
ca2oa ca2 open at long not Required. the open time of call auction phase 2, total milliseconds since January 1, 1970 0:0:0:00ms UTC
ca2ca ca2 close at long not Required. the close time of call auction phase 2, total milliseconds since January 1, 1970 0:0:0:00ms UTC
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err-code err-code string error code(returned when the interface reports an error)
err-msg err-msg string error msg(returned when the interface reports an error)

Get Market Symbols Setting

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
symbols string false symbols. NA means all symbols, multiple symbols separated with comma
ts long false timestamp to get incremental data

Note

response

{
    "status":"ok",
    "data":[
        {
            "symbol":"btc3lusdt",
            "state":"online",
            "bc":"btc3l",
            "qc":"usdt",
            "pp":4,
            "ap":4,
            "sp":"main",
            "vp":8,
            "minoa":0.01,
            "maxoa":199.0515,
            "minov":5,
            "lominoa":0.01,
            "lomaxoa":199.0515,
            "lomaxba":199.0515,
            "lomaxsa":199.0515,
            "smminoa":0.01,
            "blmlt":1.1,
            "slmgt":0.9,
            "smmaxoa":199.0515,
            "bmmaxov":2500,
            "msormlt":0.1,
            "mbormlt":0.1,
            "maxov":2500,
            "u":"btcusdt",
            "mfr":0.035,
            "ct":"23:55:00",
            "rt":"00:00:00",
            "rthr":4,
            "in":16.3568,
            "at":"enabled",
            "tags":"etp,nav,holdinglimit,activities"
        }
    ],
    "ts":"1641880897191",
    "full":1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
symbol symbol string symbol(outside)
bc base-currency string base currency
qc quote-currency string quote currency
state state string symbol status. unknown，not-online，pre-online，online，suspend，offline，transfer-board，fuse
sp symbol-partition string symbol partition
tags tags string Tags, multiple tags are separated by commas, such as: st, hadax
lr leverage_ratio decimal leverage ratio of margin symbol, provided by Global
smlr super_margin_leverage_ratio decimal leverage ratio of super-margin symbol, provided by Global
pp price-precision integer price precision
ap amount-precision integer amount precision
vp value-precision integer value precision
minoa min-order-amt decimal min order amount
maxoa max-order-amt decimal max order amount
minov min-order-value decimal min order value
lominoa limit-order-min-order-amt decimal min amount of limit price order
lomaxoa limit-order-max-order-amt decimal max amount of limit price order
lomaxba limit-order-max-buy-amt decimal max amount of limit price buy order
lomaxsa limit-order-max-sell-amt decimal max amount of limit price sell order
smminoa sell-market-min-order-amt decimal min amount of market price sell order
smmaxoa sell-market-max-order-amt decimal max amount of market price sell order
bmmaxov buy-market-max-order-value decimal max amount of market price buy order
blmlt buy-limit-must-less-than decimal(10,6) Buy limit must less than
slmgt sell-limit-must-greater-than decimal(10,6) Sell limit must greater than
msormlt market-sell-order-rate-must-less-than decimal(10,6) Market sell order rate must less than
mbormlt market-buy-order-rate-must-less-than decimal(10,6) Market buy order rate must less than
at api-trading string trading by api interface
u underlying string ETP: symbol
mfr mgmt-fee-rate decimal
ct charge-time string charge time(unix time in millisecond, just for symbols of ETP)
rt rebal-time string rebal time(unix time in millisecond, just for symbols of ETP)
rthr rebal-threshold decimal rebal threshold(just for symbols of ETP)
in init-nav decimal ETP: init nav
maxov max-order-value decimal max value of market price order
flr funding-leverage-ratio decimal C2C: funding leverage ratio
castate ca state string not Required. The state of the call auction; it will only be displayed when it is in the 1st and 2nd stage of the call auction. Enumeration values: "ca_1", "ca_2"
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err-code err-code string error code(returned when the interface reports an error)
err-msg err-msg string error msg(returned when the interface reports an error)

Get Chains Information

API Key Permission：Read

Request Parameters

Parameter Data Type Required Description
show-desc string false show desc, 0: no, 1: all, 2: suspend deposit/withdrawal and chain exchange
currency string false currency
ts long false timestamp to get incremental data

Note

response

{
    "status": "ok",
    "data": [
        {
            "chain": "hrc20nft",
            "currency": "nft",
            "code": "hrc20nft",
            "ct": "live",
            "ac": "eth",
            "default": 0,
            "dma": "160298",
            "wma": "160298",
            "de": true,
            "we": true,
            "wp": 6,
            "ft": "eth",
            "dn": "HECO",
            "fn": "",
            "awt": false,
            "adt": false,
            "ao": false,
            "fc": 10,
            "sc": 20,
            "v": true,
            "sda": "",
            "swa": "",
            "deposit-tips-desc": "Minimum deposit amount:160298\nAny deposits less than the minimum amount will not be credited or refunded.",
            "withdraw-desc": "Minimum withdrawal amount: 160298 NFT(HECO). !>_<!To ensure the safety of your funds, your withdrawal request will be manually reviewed if your security strategy or password is changed. Please wait for phone calls or emails from our staff.!>_<!Please make sure that your computer and browser are secure and your information is protected from being tampered or leaked.",
            "suspend-deposit-desc": "",
            "suspend-withdraw-desc": "",
            "replace-chain-info-desc": "",
            "replace-chain-notification-desc": "",
            "replace-chain-popup-desc": ""
        }
    ],
    "ts": "1641880897191",
    "full": 1
}

Response Content

Parameter Full Name Data Type Description
status status string status
data <data> Object
adt addr-deposit-tag boolean has addr deposit tag
ac address-chain string address of chain
ao addr-oneoff boolean addr oneoff
awt addr-with-tag boolean addr with tag
chain chain string chain name
ct chain-type string chain type. plain, live, old, new, legal, tooold
code code string obsolete, please to use chain
currency currency string currency
deposit-desc deposit-desc string deposit desc
de deposit-enable boolean deposit enable
dma deposit-min-amount string deposit-min-amount, if the amount is less than this amount will be: 1. The small amount will exceed the deposit-min-amount and then be credited 2. The small amount will not be accumulated and will never be credited to the account
deposit-tips-desc deposit-tips-desc string deposit tips desc
dn display-name string display name, general be upper
fc fast-confirms integer fast-confirms, when height of the exchange node to that chain tail is greater than this number, the deposit and withdrawal will be not settled to the user account, this deposit order is regarded as an unsafe deposit, and the available amount in the withdrawal and account transfer must be excluded that amount from this order.
ft fee-type string fee type
default is-default integer is default
replace-chain-info-desc replace-chain-info-desc string replace chain info desc
replace-chain-notification-desc replace-chain-notification-desc string replace chain notification desc
replace-chain-popup-desc replace-chain-popup-desc string replace chain popup desc
sc safe-confirms integer safe confirms, When the distance between the height of the current exchange's chain node and the chain tail is greater than this number, the asset management DW will mark this order as a safe deposit, and it will be regarded as the available amount when withdrawing and transferring funds.
sda suspend-deposit-announcement string suspend deposit announcement
suspend-deposit-desc suspend-deposit-desc string suspend deposit desc
swa suspend-withdraw-announcement string suspend withdraw announcement
suspend-withdraw-desc suspend-withdraw-desc string suspend withdraw desc
v visible boolean visible
withdraw-desc withdraw-desc string withdraw desc
we withdraw-enable boolean withdraw enable
wma withdraw-min-amount string withdraw min amount, refused to withdraw if less than this amount
wp withdraw-precision integer withdraw precision, refused to withdraw if greater than this amount
fn full-name string
withdraw-tips-desc withdraw-tips-desc string withdraw tips desc
suspend-visible-desc suspend-visible-desc string suspend visible desc
</data>
ts ts String timestamp of incremental data
full full int full data flag: 0 for no and 1 for yes
err-code err-code string error code(returned when the interface reports an error)
err-msg err-msg string error msg(returned when the interface reports an error)

APIv2 - Currency & Chains

API user could query static reference information for each currency, as well as its corresponding chain(s). (Public Endpoint)

HTTP Request

curl "https://api.huobi.pro/v2/reference/currencies?currency=usdt"

Request Parameters

Field Name Required Data Type Description Value Range
currency false string Currency btc, ltc, bch, eth, etc ...(available currencies in Huobi)
authorizedUser false boolean Authorized user true or false (if not filled, default value is true)

Response:

{
    "code":200,
    "data":[
        {
            "chains":[
                {
                    "chain":"trc20usdt",
                    "displayName":"",
                    "baseChain": "TRX",
                    "baseChainProtocol": "TRC20",
                    "isDynamic": false,
                    "depositStatus":"allowed",
                    "maxTransactFeeWithdraw":"1.00000000",
                    "maxWithdrawAmt":"280000.00000000",
                    "minDepositAmt":"100",
                    "minTransactFeeWithdraw":"0.10000000",
                    "minWithdrawAmt":"0.01",
                    "numOfConfirmations":999,
                    "numOfFastConfirmations":999,
                    "withdrawFeeType":"circulated",
                    "withdrawPrecision":5,
                    "withdrawQuotaPerDay":"280000.00000000",
                    "withdrawQuotaPerYear":"2800000.00000000",
                    "withdrawQuotaTotal":"2800000.00000000",
                    "withdrawStatus":"allowed"
                },
                {
                    "chain":"usdt",
                    "displayName":"",
                    "baseChain": "BTC",
                    "baseChainProtocol": "OMNI",
                    "isDynamic": false,
                    "depositStatus":"allowed",
                    "maxWithdrawAmt":"19000.00000000",
                    "minDepositAmt":"0.0001",
                    "minWithdrawAmt":"2",
                    "numOfConfirmations":30,
                    "numOfFastConfirmations":15,
                    "transactFeeRateWithdraw":"0.00100000",
                    "withdrawFeeType":"ratio",
                    "withdrawPrecision":7,
                    "withdrawQuotaPerDay":"90000.00000000",
                    "withdrawQuotaPerYear":"111000.00000000",
                    "withdrawQuotaTotal":"1110000.00000000",
                    "withdrawStatus":"allowed"
                },
                {
                    "chain":"usdterc20",
                    "displayName":"",
                    "baseChain": "ETH",
                    "baseChainProtocol": "ERC20",
                    "isDynamic": false,
                    "depositStatus":"allowed",
                    "maxWithdrawAmt":"18000.00000000",
                    "minDepositAmt":"100",
                    "minWithdrawAmt":"1",
                    "numOfConfirmations":999,
                    "numOfFastConfirmations":999,
                    "transactFeeWithdraw":"0.10000000",
                    "withdrawFeeType":"fixed",
                    "withdrawPrecision":6,
                    "withdrawQuotaPerDay":"180000.00000000",
                    "withdrawQuotaPerYear":"200000.00000000",
                    "withdrawQuotaTotal":"300000.00000000",
                    "withdrawStatus":"allowed"
                }
            ],
            "currency":"usdt",
            "instStatus":"normal"
        }
    ]
}

Response Content

Field Name Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
currency true string Currency
<chains> true object
chain true string Chain name
displayName true string Chain display name
baseChain false string Base chain name
baseChainProtocol false string Base chain protocol
isDynamic false boolean Is dynamic fee type or not (only applicable to withdrawFeeType = fixed) true,false
numOfConfirmations true int Number of confirmations required for deposit success (trading & withdrawal allowed once reached)
numOfFastConfirmations true int Number of confirmations required for quick success (trading allowed but withdrawal disallowed once reached)
minDepositAmt true string Minimal deposit amount in each request
depositStatus true string Deposit status allowed,prohibited
minWithdrawAmt true string Minimal withdraw amount in each request
maxWithdrawAmt true string Maximum withdraw amount in each request
withdrawQuotaPerDay true string Maximum withdraw amount in a day (Singapore timezone)
withdrawQuotaPerYear true string Maximum withdraw amount in a year
withdrawQuotaTotal true string Maximum withdraw amount in total
withdrawPrecision true int Withdraw amount precision
withdrawFeeType true string Type of withdraw fee (only one type can be applied to each currency) fixed,circulated,ratio
transactFeeWithdraw false string Withdraw fee in each request (only applicable to withdrawFeeType = fixed)
minTransactFeeWithdraw false string Minimal withdraw fee in each request (only applicable to withdrawFeeType = circulated or ratio)
maxTransactFeeWithdraw false string Maximum withdraw fee in each request (only applicable to withdrawFeeType = circulated or ratio)
transactFeeRateWithdraw false string Withdraw fee in each request (only applicable to withdrawFeeType = ratio)
withdrawStatus true string Withdraw status allowed,prohibited
</data>
instStatus true string Instrument status normal,delisted
</chains>

Status Code

Status Code Error Message Scenario
200 success Request successful
500 error System error
2002 invalid field value in "field name" Invalid field value

Get Current Timestamp

This endpoint returns the current timestamp, i.e. the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970. 

curl "https://api.huobi.pro/v1/common/timestamp"

HTTP Request

Request Parameters

No parameter is needed for this endpoint.

Response:

{
    "status":"ok",
    "data":1629715504949
}

Response Content

参数名称 是否必须 类型 描述 取值范围
status true string Request Processing Result
data true long current system timestamp

Market Data

Introduction

Market data APIs provide public market information such as varies of candlestick, depth and trade information.

The market data is updated once per second.

Get Klines(Candles)

This endpoint retrieves all klines in a specific range.

HTTP Request

curl "https://api.huobi.pro/market/history/kline?period=1day&size=200&symbol=btcusdt"

Query Parameters

Parameter Data Type Required Default Description Value Range
symbol string true NA The trading symbol to query All trading symbol supported, e.g. btcusdt, bccbtcn (to retrieve candlesticks for ETP NAV, symbol = ETP trading symbol + suffix 'nav'，for example: btc3lusdtnav)
period string true NA The period of each candle 1min, 5min, 15min, 30min, 60min, 4hour, 1day, 1mon, 1week, 1year
size integer false 150 The number of data returns [1-2000]

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.kline.5min",
    "status": "ok",
    "ts": 1629769247172,
    "data": [
        {
            "id": 1629769200,
            "open": 49056.37,
            "close": 49025.51,
            "low": 49022.86,
            "high": 49056.38,
            "amount": 3.946281917950917,
            "vol": 193489.67275732,
            "count": 196
        },
        {
            "id": 1629768900,
            "open": 48994.61,
            "close": 49056.37,
            "low": 48966.72,
            "high": 49072.46,
            "amount": 30.72223099519689,
            "vol": 1505870.732227976,
            "count": 1504
        }
    ]
}

Response Content

Field Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format：market.$symbol.kline.$period
ts long Time of Respond Generation, Unit: Millisecond
<data> object
id long The UNIX timestamp in seconds as response id
amount float Accumulated trading volume, in base currency
count integer The number of completed trades
open float The opening price
close float The closing price
low float The low price
high float The high price
vol float Accumulated trading value, in quote currency
</data>

Get Latest Aggregated Ticker

This endpoint retrieves the latest ticker with some important 24h aggregated market data.

HTTP Request

curl "https://api.huobi.pro/market/detail/merged?symbol=ethusdt"

Request Parameters

Parameter Data Type Required Default Description Value Range
symbol string true NA The trading symbol to query All supported trading symbol, e.g. btcusdt, bccbtc.Refer to /v1/common/symbols

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.detail.merged",
    "status": "ok",
    "ts": 1629788763750,
    "tick": {
        "id": 272156789143,
        "version": 272156789143,
        "open": 50080.0,
        "close": 49820.92,
        "low": 48767.0,
        "high": 50500.0,
        "amount": 12055.365781937457,
        "vol": 5.985618685709001E8,
        "count": 420573,
        "bid": [
            49819.48,
            2.58112
        ],
        "ask": [
            49819.49,
            0.002411
        ]
    }
}

Response Content

Field Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format：market.$symbol.detail.merged
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id long The internal identity
amount float Accumulated trading volume of last 24 hours (rotating 24h), in base currency
count integer The number of completed trades (rotating 24h)
open float The opening price of last 24 hours (rotating 24h)
close float The last price of last 24 hours (rotating 24h)
low float The lowest price of last 24 hours (rotating 24h)
high float The highest price of last 24 hours (rotating 24h)
vol float Accumulated trading value of last 24 hours (rotating 24h), in quote currency
bid object The current best bid in format [price, size]
ask object The current best ask in format [price, size]
</tick>

Get Latest Tickers for All Pairs

This endpoint retrieves the latest tickers for all supported pairs.

HTTP Request

curl "https://api.huobi.pro/market/tickers"

Request Parameters

No parameters are needed for this endpoint.

The above command returns JSON structured like this:

{
    "status":"ok",
    "ts":1629789355531,
    "data":[
        {
            "symbol":"smtusdt",
            "open":0.004659,     
            "high":0.004696,     
            "low":0.0046,        
            "close":0.00468,     
            "amount":36551302.17544405,
            "vol":170526.0643855023,
            "count":1709,
            "bid":0.004651,
            "bidSize":54300.341,
            "ask":0.004679,
            "askSize":1923.4879
        },
        {
            "symbol":"ltcht",
            "open":12.795626,
            "high":12.918053,
            "low":12.568926,
            "close":12.918053,
            "amount":1131.801675005825,
            "vol":14506.9381937385,
            "count":923,
            "bid":12.912687,
            "bidSize":0.1068,
            "ask":12.927032,
            "askSize":5.3228
        }
    ]
}

Response Content

Response content is an array of object, each object has below fields.

Field Data Type Description
status string Request Processing Result "ok","error"
ts long Time of Respond Generation, Unit: Millisecond
<data> object
amount float The aggregated trading volume in last 24 hours (rotating 24h)
count integer The number of completed trades of last 24 hours (rotating 24h)
open float The opening price of a nature day (Singapore time)
close float The closing price of a nature day (Singapore time)
low float The lowest price of a nature day (Singapore time)
high float The highest price of a nature day (Singapore time)
vol float The aggregated trading value in last 24 hours (rotating 24h)
symbol string The trading symbol of this object, e.g. btcusdt, bccbtc
bid float Best bid price
bidSize float Best bid size
ask float Best ask price
askSize float Best ask size
</data>

Get Market Depth

This endpoint retrieves the current order book of a specific pair.

HTTP Request

curl "https://api.huobi.pro/market/depth?symbol=btcusdt&type=step0"

Request Parameters

Parameter Data Type Required Default Value Description Value Range
symbol string true NA The trading symbol to query Refer to GET /v1/common/symbols
depth integer false 20 The number of market depth to return on each side 5, 10, 20
type string true step0 Market depth aggregation level, details below step0, step1, step2, step3, step4, step5

"type" Details

Value Description
step0 No market depth aggregation
step1 Aggregation level = precision*10
step2 Aggregation level = precision*100
step3 Aggregation level = precision*1000
step4 Aggregation level = precision*10000
step5 Aggregation level = precision*100000

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.depth.step0",
    "status": "ok",
    "ts": 1629790438801,
    "tick": {
        "ts": 1629790438215,
        "version": 136107114472,
        "bids": [
            [
                49790.87,
                0.779876
            ],
            [
                49785.9,
                1.82E-4
            ],
            [
                49784.48,
                0.002758
            ],
            [
                49784.29,
                0.05
            ],
            [
                49783.06,
                0.005038
            ]
        ],
        "asks": [
            [
                49790.88,
                2.980472
            ],
            [
                49790.89,
                0.006613
            ],
            [
                49792.16,
                0.080302
            ],
            [
                49792.67,
                0.030112
            ],
            [
                49793.23,
                0.043103
            ]
        ]
    }
}

Response Content

Field Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format： market.$symbol.depth.$type
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
ts integer The UNIX timestamp in milliseconds is adjusted to Singapore time
version integer Internal data
bids object The current all bids in format [price, size]
asks object The current all asks in format [price, size]
</tick>

Get the Last Trade

This endpoint retrieves the latest trade with its price, volume, and direction.

HTTP Request

curl "https://api.huobi.pro/market/trade?symbol=ethusdt"

Request Parameters

Parameter Data Type Required Default Value Description Value Range
symbol string true NA The trading symbol to query Refer to GET /v1/common/symbols

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.trade.detail",
    "status": "ok",
    "ts": 1629792192037,
    "tick": {
        "id": 136107843051,
        "ts": 1629792191928,
        "data": [
            {
                "id": 136107843051348400221001656,
                "ts": 1629792191928,
                "trade-id": 102517374388,
                "amount": 0.028416,
                "price": 49806.0,
                "direction": "buy"
            },
            {
                "id": 136107843051348400229813302,
                "ts": 1629792191928,
                "trade-id": 102517374387,
                "amount": 0.025794,
                "price": 49806.0,
                "direction": "buy"
            }
        ]
    }
}

Response Content

Parameter Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format：market.$symbol.trade.detail
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id long global transaction ID
ts long Latest Creation Time
<data> object
id integer The unique trade id of this trade (to be obsoleted)
trade-id integer The unique trade id (NEW)
amount float The trading volume in base currency
price float The trading price in quote currency
ts integer The UNIX timestamp in milliseconds adjusted to Singapore time
direction string The direction of the taker trade: 'buy' or 'sell'
</data>
</tick>

Get the Most Recent Trades

This endpoint retrieves the most recent trades with their price, volume, and direction.

HTTP Request

curl "https://api.huobi.pro/market/history/trade?symbol=ethusdt&size=2"

Request Parameters

Parameter Data Type Required Default Value Description Value Range
symbol string true NA The trading symbol to query All supported trading symbol, e.g. btcusdt, bccbtc.Refer to GET /v1/common/symbols
size integer false 1 The number of data returns [1-2000]

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.trade.detail",
    "status": "ok",
    "ts": 1629793657842,
    "data": [
        {
            "id": 136108764379,
            "ts": 1629793656939,
            "data": [
                {
                    "id": 136108764379348400430265987,
                    "ts": 1629793656939,
                    "trade-id": 102517381182,
                    "amount": 1.24E-4,
                    "price": 49656.4,
                    "direction": "buy"
                }
            ]
        },
        {
            "id": 136108763320,
            "ts": 1629793656198,
            "data": [
                {
                    "id": 136108763320348400439066863,
                    "ts": 1629793656198,
                    "trade-id": 102517381181,
                    "amount": 0.01125,
                    "price": 49655.0,
                    "direction": "buy"
                },
                {
                    "id": 136108763320348400429773626,
                    "ts": 1629793656198,
                    "trade-id": 102517381180,
                    "amount": 8.3E-4,
                    "price": 49651.35,
                    "direction": "buy"
                }
            ]
        }
    ]
}

Response Content

Field Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format：market.$symbol.trade.detail
ts long Time of Respond Generation, Unit: Millisecond
<data> object
id long global transaction ID
ts long Latest Creation Time
<data> object
id integer The unique trade id of this trade (to be obsoleted)
trade-id integer The unique trade id (NEW)
amount float The trading volume in base currency
price float The trading price in quote currency
ts integer The UNIX timestamp in milliseconds adjusted to Singapore time
direction string The direction of the taker trade: 'buy' or 'sell'
</data>
</data>

Get the Last 24h Market Summary

This endpoint retrieves the summary of trading in the market for the last 24 hours.

HTTP Request

curl "https://api.huobi.pro/market/detail?symbol=ethusdt"

Request Parameters

Parameter Data Type Required Default Value Description Value Range
symbol string true NA The trading symbol to query Refer to /v1/common/symbols

The above command returns JSON structured like this:

{
    "ch": "market.btcusdt.detail",
    "status": "ok",
    "ts": 1629795484817,
    "tick": {
        "id": 272164011416,
        "low": 48767.0,
        "high": 50500.0,
        "open": 50266.89,
        "close": 49728.71,
        "vol": 6.010379336834868E8,
        "amount": 12110.642402972368,
        "version": 272164011416,
        "count": 420452
    }
}

Response Content

Field Data Type Description
status string Request Processing Result "ok","error"
ch string Data belonged channel，Format： market.$symbol.detail
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id integer The internal identity
amount float The aggregated trading volume in USDT of last 24 hours (rotating 24h)
count integer The number of completed trades of last 24 hours (rotating 24h)
open float The opening price of last 24 hours (rotating 24h)
close float The closing price of last 24 hours (rotating 24h)
low float The lowest price of last 24 hours (rotating 24h)
high float The highest price of last 24 hours (rotating 24h)
vol float The trading volume in base currency of last 24 hours (rotating 24h)
version integer Internal data
</tick>

Error Code

Below is the error code, error message and description returned by Market data APIs.

Error Code Error Message Description
invalid-parameter invalid symbol Parameter symbol is invalid
invalid-parameter invalid period Parameter period is invalid for candlestick data
invalid-parameter invalid depth Parameter depth is invalid for depth data
invalid-parameter invalid type Parameter type is invalid
invalid-parameter invalid size Parameter size is invalid
invalid-parameter invalid size,valid range: [1, 2000] Parameter size range is invalid
invalid-parameter request timeout Request timeout please try again

Account

Introduction

Account APIs provide account related (such as basic info, balance, history, point) query and transfer functionality.

Get all Accounts of the Current User

API Key Permission：Read
Rate Limit (NEW): 100times/2s

This endpoint returns a list of accounts owned by this API user.

HTTP Request

Request Parameters

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "id": 10000001,
            "type": "spot",
            "subtype": "",
            "state": "working"
        },
        {
            "id": 10000002,
            "type": "otc",
            "subtype": "",
            "state": "working"
        },
        {
            "id": 10000003,
            "type": "point",
            "subtype": "",
            "state": "working"
        }
    ]
}

Response Content

Field Data Type Description Value Range
status true string Request Processing Result
<data> true object
id integer Unique account id NA
state string Account state working, lock
type string The type of this account spot, margin, otc, point, super-margin, investment, borrow, grid-trading, deposit-earning, otc-options
subtype string The type of sub account (applicable only for isolated margin accout) The corresponding trading symbol (currency pair) the isolated margin is based on, e.g. btcusdt
</data> true object

Get Account Balance of a Specific Account

API Key Permission：Read
Rate Limit (NEW): 100times/2s

This endpoint returns the balance of an account specified by account id.

HTTP Request

'account-id': The specified account id to get balance for, can be found by query '/v1/account/accounts' endpoint.

Request Parameters

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": {
        "id": 1000001,
        "type": "spot",
        "state": "working",
        "list": [
            {
                "currency": "usdt",
                "type": "trade",
                "balance": "91.850043797676510303",
                "seq-num": "477"
            },
            {
                "currency": "usdt",
                "type": "frozen",
                "balance": "5.160000000000000015",
                "seq-num": "477"
            },
            {
                "currency": "poly",
                "type": "trade",
                "balance": "147.928994082840236",
                "seq-num": "2"
            }
        ]
    }
}

Response Content

Field Data Type Description Value Range
status string Request Processing Result "ok","error"
<data> object
id integer Unique account id NA
state string Account state working, lock
type string The type of this account spot, margin, otc, point, super-margin, investment, borrow，minepool, etf, crypto-loans, deposit-earning, grid-trading, otc-options
<list> Array
currency string The currency of this balance NA
type string The balance type trade, frozen, loan, interest, lock, bank
balance string The balance in the main currency unit NA
seq-num string Serial Number of Account Change NA
</list>
</data>

Get The Total Valuation of Platform Assets

permission type：Read

API Rate Limit(NEW）：3/1s

Obtain the total asset valuation of the platform account according to the BTC or legal currency denominated unit.

HTTP Request

Query Parameters

Parameter Required Data Type Description Value Range
accountType false string account type, more to see "Account type data dictionary"
valuationCurrency false string If not filled, the default is BTC (only BTC supported now, and must be capitalized)

Responds:

{
    "code": 200,
    "data": {
        "updated": {
            "success": true,
            "time": 1629916724000
        },
        "todayProfitRate": "0.004638293764657609",
        "totalBalance": "0.06276321",
        "todayProfit": "0.00028977",
        "profitAccountBalanceList": [
            {
                "distributionType": "11",
                "balance": 0.05728808,
                "success": true,
                "accountBalance": "0.05728808"
            }
        ]
    },
    "success": true
}

Response Content

Parameter Required Data Type Description
code TRUE int status code
<data> TRUE object
totalBalance TRUE string total balance
todayProfit TRUE string today profit
todayProfitRate TRUE string today profit rate
<profitAccountBalanceList> TRUE list
distributionType TRUE string distribution type
balance TRUE float balance
success TRUE boolean get data successful or not. When fails, the accountBalance and balance are 0
accountBalance TRUE string account balance
</profitAccountBalanceList>
<updated> TRUE list
success TRUE boolean updated today, yes or not
time TRUE long updated time
</updated>
</data>
success TRUE boolean

Account type data dictionary

code description
1 spot
2 Isolated
3 cross
4 coin futures
5 flat
6 minepool
7 coin swaps
8 investment
9 borrow
10 earn
11 usdt swaps
12 option
13 otc-options
14 crypto-loans
15 grid-trading
16 minepool

Get Asset Valuation

API Key Permission：Read

Rate Limit (NEW): 100times/2s

This endpoint returns the valuation of the total assets of the account in btc or fiat currency.

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Value Range
accountType true string The type of this account NA spot, margin, otc, super-margin
valuationCurrency false string The valuation according to the certain fiat currency BTC BTC, CNY, USD, JPY, KRW, GBP, TRY, EUR, RUB, VND, HKD, TWD, MYR, SGD, AED, SAR (case sensitive)
subUid false long Sub User's UID. When sub user's UID is not specified, the response would include the records of API key. NA

The above command returns JSON structured like this:

{
    "code": 200,
    "data": {
        "balance": "34.75",
        "timestamp": 1594901254363
    },
    "ok": true
}

Response Content

Parameter Required Data Type Description
code true string status code
ok true string
<data> true object
balance true string The valuation according to the certain fiat currency
timestamp true long Return time
</data>

Asset Transfer

API Key Permission：Trade

This endpoint allows parent user and sub user to transfer asset between accounts.

Features now supported for both parent user and sub user include:
1.transfer asset between spot account and individual isolated-margin account;
2.transfer asset between individual isolated-margin accounts;

Features now supported for parent user include:
1.Transfer asset between parent user's spot account and sub user's spot account;
2.Transfer asset from sub user’s spot account to another sub user’s spot account that is under the same parent user;

Features now supported for sub user include:
1.Transfer asset from authorized sub user’s spot account to another sub user’s spot account that is under the same parent user.The authorization endpoint is POST /v2/sub-user/transferability.
2.Transfer asset from sub user’s spot account to parent user’s spot account;

Other transfer functions will be gradually launched later, please take note on API announcement in near future.

HTTP Request

Request Parameters

Parameter Required Data Type Description Values
from-user true long Transfer out user uid parent user uid, sub user uid
from-account-type true string Transfer out account type spot, margin
from-account true long Transfer out account id
to-user true long Transfer in user uid parent user uid, sub user uid
to-account-type true string Transfer in account type spot, margin
to-account true long Transfer in account id
currency true string Currency name Refer to GET /v1/common/currencys
amount true string Amount of fund to transfer

Response:

{
    "status": "ok",
    "data": {
        "transact-id": 220521190,
        "transact-time": 1590662591832
    }
}

Response Content

Field Required Data Type Description Values
status true string Request status "ok" or "error"
<data> true list
transact-id true int Transfer id
transact-time true long Transfer time
</data>

Get Account History

API Key Permission：Read
Rate Limit (NEW): 5times/2s

This endpoint returns the amount changes of a specified user's account.

HTTP Request

curl "https://api.huobi.pro/v1/account/history?account-id=5260185"

Request Parameters

Parameter Required Data Type Description Default Value Value Range
account-id true string Account Id, refer to GET /v1/account/accounts
currency false string Currency name Refer to /v1/common/currencys
transact-types false string Amount change types (multiple selection allowed, separated by comma) all trade,etf, transact-fee, fee-deduction, transfer, credit, liquidation, interest, deposit, withdraw, withdraw-fee, exchange, other-types, rebate
start-time false long The start time of the query window (unix time in millisecond). Searching based on transact-time. The maximum size of the query window is 1 hour. The query window can be shifted within 30 days. ((end-time) – 1hour) [((end-time) – 1hour), (end-time)]
end-time false long The end time of the query window (unix time in millisecond). Searching based on transact-time. The maximum size of the query window is 1 hour. The query window can be shifted within 30 days. current-time [(current-time) – 29days,(current-time)]
sort false string Sorting order asc asc or desc
size false int Maximum number of items in each response 100 [1-500]
from-id false long First record ID in this query (only valid for next page querying, see Note 2)

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "account-id": 10000001,
            "currency": "usdt",
            "record-id": 359044707902783794,
            "transact-amt": "-10.000000000000000000",
            "transact-type": "other-types",
            "avail-balance": "81.850043797676510303",
            "acct-balance": "97.010043797676510318",
            "transact-time": 1629882096557
        },
        {
            "account-id": 10000001,
            "currency": "usdt",
            "record-id": 359044690723242123,
            "transact-amt": "-10.000000000000000000",
            "transact-type": "transfer",
            "avail-balance": "81.850043797676510303",
            "acct-balance": "87.010043797676510318",
            "transact-time": 1629882096569
        }
    ],
    "next-id": 47996522235
}

Response Content

Field Data Type Description Value Range
status string Status code
<data> object
account-id long Account ID
currency string Currency
transact-amt string Amount change (positive value if income, negative value if outcome)
transact-type string Amount change types
avail-balance string Available balance
acct-balance string Account balance
transact-time long Transaction time (database time)
record-id long Unique record ID in the database
</data>
next-id long First record ID in next page (only valid if exceeded page size, see Note 2)

Note 1:

Note 2:
Only when the number of items within the query window (between "start-time" and "end-time") exceeded the page limitation (defined by "size"), Huobi server returns "next-id". Once received "next-id", API user should –

1) Be aware of that, some items within the query window were not returned due to the page size limitation.
2) In order to get these items from Huobi server, adopt the "next-id" as "from-id" and submit another request, with other request parameters no change.
3) As database record ID, "next-id" and "from-id" are for recurring query purpose and the ID itself does not have any business implication.

Note 3:

Change type contains a detailed list of account types：

Transact Type Account Type
trade match-income
trade match-payout
trade otc-trade
trade point-purchased
trade point-purchased-pay
trade member-purchase
trade matching-transfer-frozen-to-clearing-v2
trade matching-transfer-clearing-to-trade-v2
trade otc-options-user-to-principal-clct-v2
trade otc-options-income-to-user-v2
etf etf-subscription-apply-transfer
etf etf-subscription-apply-cancel
etf etf-subscription-settle-transfer
etf etf-subscription-apply-receivable
etf etf-subscription-settle-receivable
etf etf-subscription-open-position-todo
etf etf-subscription-open-position-done
etf etf-purchase-cancel
etf etf-purchase-apply-transfer
etf etf-purchase-settle-transfer
etf etf-redemption-cancel
etf etf-redemption-apply-transfer
etf etf-redemption-settle-transfer
transact-fee matching-transfer-fee-v2
transact-fee otc-trade-fee
transact-fee point-etf-fee-deduction
transact-fee otc-charge-in
transact-fee otc-charge-out
transact-fee etf-subscription-charge-receivable
transact-fee matching-transfer-fee-v3
fee-deduction point-fee-deduction-v3
fee-deduction point-fee-deduction-pay-v2
fee-deduction point-fee-deduction-pay-v3
fee-deduction revert-point-fee-deduction-pay
fee-deduction point-interest-deduction-pay
fee-deduction point-etf-fee-deduction-pay
fee-deduction trade-fee-deduction
fee-deduction otc-point-pay
fee-deduction trade-fee-deduction-pay-user-trade-to-match
fee-deduction trade-fee-deduction-user-trade-to-match
fee-deduction revert-point-fee-deduction
fee-deduction super-margin-interest-deduct-repay
transfer user-account-transfer-inner-in
transfer user-account-transfer-inner-out
transfer mine-account-to-user-account
transfer user-account-to-mine-account
transfer otc-transfer-in
transfer otc-transfer-in-v2
transfer otc-transfer-out
transfer otc-transfer-out-v2
transfer margin-transfer-in
transfer margin-transfer-out
transfer point-transfer
transfer point-transfer-pay
transfer mine-pool-transfer-in
transfer mine-pool-transfer-out
transfer chat-transfer-in
transfer chat-transfer-in-v2
transfer chat-transfer-out
transfer chat-transfer-out-v2
transfer chat-to-otc
transfer otc-to-chat
transfer master-transfer-in
transfer master-transfer-out
transfer margin-to-margin
transfer master-point-transfer-in
transfer master-point-transfer-out
transfer sub-transfer
transfer sub-point-transfer
transfer futures-transfer-in
transfer futures-transfer-in-v2
transfer futures-transfer-out
transfer futures-transfer-out-v2
transfer institution-transfer-in
transfer institution-transfer-in-v2
transfer institution-transfer-out
transfer institution-transfer-out-v2
transfer swap-transfer-in
transfer swap-transfer-out
transfer dm-swap-transfer-in
transfer dm-swap-transfer-out
transfer option-transfer-in
transfer option-transfer-out
transfer cfd-transfer-in
transfer cfd-transfer-out
transfer super-margin-transfer-out
transfer super-margin-transfer-in
transfer japan-donations-operation-to-system
transfer japan-donations-system-to-operation
transfer japan-donations-system-to-user
transfer japan-donations-user-to-system
transfer japan-discount-user-to-system
transfer japan-discount-system-to-user
transfer japan-discount-operation-to-system
transfer japan-discount-system-to-operation
transfer directed-card-system-to-operation
transfer directed-card-operation-to-system
transfer system-to-user-account
transfer user-account-to-system
transfer liquidity-account-to-system
transfer system-to-liquidity-account
transfer linear-swap-transfer-in
transfer linear-swap-transfer-out
transfer custody-transfer-in
transfer custody-transfer-out
transfer operation-to-margin-trade
transfer margin-trade-to-operation
transfer grid-transfer-in
transfer grid-transfer-out
transfer otc-generic-transfer-in
transfer otc-generic-transfer-out
transfer spot-generic-transfer-in
transfer spot-generic-transfer-out
transfer margin-generic-transfer-in
transfer margin-generic-transfer-out
transfer point-generic-transfer-in
transfer point-generic-transfer-out
transfer minepool-generic-transfer-in
transfer minepool-generic-transfer-out
transfer super-margin-generic-transfer-in
transfer super-margin-generic-transfer-out
transfer investment-generic-transfer-in
transfer investment-generic-transfer-out
transfer borrow-generic-transfer-in
transfer borrow-generic-transfer-out
transfer deposit-earning-generic-transfer-in
transfer deposit-earning-generic-transfer-out
transfer crypto-loans-generic-transfer-in
transfer crypto-loans-generic-transfer-out
transfer grid-trading-generic-transfer-in
transfer grid-trading-generic-transfer-out
transfer mine-pool-mall-lease-spot-to-settlement-system
transfer mine-pool-mall-lease-settlement-system-to-spot
transfer kr-savings-spot-to-clct
transfer kr-savings-clct-to-transition-spot
transfer kr-savings-transition-spot-to-intermediate
transfer kr-savings-return-to-spot
transfer kr-savings-income-to-spot
transfer kr-savings-transition-spot-to-clct
transfer jp-coupon-ops-to-sys
transfer jp-coupon-sys-to-spot
transfer otc-options-master-transfer-in
transfer otc-options-master-transfer-in-manual
transfer otc-options-master-transfer-out
transfer otc-options-master-transfer-out-manual
transfer mine-pool-staking-lock
transfer mine-pool-staking-unlock
transfer mine-pool-staking-reward-system-to-spot
transfer airdrop-user-spot-oneside-in
transfer project-airdrop-user-spot-oneside-in
credit margin-loan-transfer
credit margin-loan-transfer-v2
credit margin-repay-loan-transfer
credit margin-repay-loan-transfer-v2
credit super-margin-loan-transfer
credit super-margin-repay
credit auto-super-margin-repay
credit operations-account-recycling-user-trade-principal
credit operations-account-to-outside-loan-account
credit outside-loan-account-to-operations-account
credit pledged-loan-lending
credit pledged-loan-receiving
credit super-margin-loan-receivable
credit super-margin-interest-accrued
credit super-margin-interest-deduct-refund
credit super-margin-refund
credit margin-repay-loan-receivable
credit margin-repay-loan-receivable-v2
credit otc-options-user-asset-ops-borrow
credit otc-options-user-asset-ops-borrow-debt
credit otc-options-user-asset-ops-repay
credit otc-options-user-asset-ops-repay-debt
liquidation margin-auto-repay-interest-transfer
liquidation margin-auto-repay-interest-transfer-v2
liquidation margin-auto-repay-loan-transfer
liquidation margin-auto-repay-loan-transfer-v2
interest margin-repay-interest-transfer
interest margin-repay-interest-transfer-v2
interest point-interest-deduction
interest super-margin-interest-repay
interest auto-super-margin-interest-repay
interest margin-repay-interest-receivable
interest margin-repay-interest-receivable-v2
interest margin-interest-accrued
interest margin-interest-accrued-v2
deposit user-account-deposit
deposit user-account-fast-deposit
deposit user-credit-loan-to-system
deposit user-account-mgt-special-deposit
deposit operations-account-deposit-compensate-expenditure
deposit operations-account-deposit-compensate-earning
withdraw user-apply-withdraw
withdraw user-apply-fiat-withdraw
withdraw user-account-withdraw
withdraw user-account-fast-withdraw
withdraw operations-account-withdraw-compensate-expenditure
withdraw operations-account-withdraw-compensate-earning
withdraw-fee system-withdraw-fee-in
withdraw-fee system-withdraw-fee-out
exchange stable-currency-transfer-in-v2
exchange stable-currency-transfer-out-v2
rebate negative-maker-sys-oneside-out
rebate negative-maker-user-oneside-in
etp etp-purchase-transfer
etp etp-purchase-receivable
etp etp-purchase-charge
etp etp-redemption-transfer
etp etp-redemption-settle-transfer
etp etp-redemption-charge
etp etp-management-charge
etp etp-cash-concentration
etp etp-usdt-hedge-sys-to-user
etp etp-usdt-hedge-user-to-sys
etp etp-futures-hedge-sys-to-user
etp etp-futures-hedge-user-to-sys
etp etp-usdt-spot-sys-to-user
etp etp-usdt-spot-user-to-sys
savings deposit-earning-to-spot
savings spot-to-deposit-earning
savings deposit-earning-to-collect
savings collect-to-deposit-earning
savings operation-to-collect
savings collect-to-operation
savings operation-to-interest
savings interest-to-operation
savings interest-to-deposit-earning
savings deposit-earning-to-interest
savings collect-to-expend
savings expend-to-collect
savings expend-to-operation
savings operation-to-expend
other-types operations-account-transfer-in
other-types operations-account-transfer-out
other-types operations-account-user-event-in
other-types operations-account-user-event-out
other-types operations-account-loan-to-user-trade
other-types operations-account-expenditure
other-types inspire-account-to-user-account
other-types user-account-to-inspire-account
other-types activity-account-to-user-account
other-types user-account-to-activity-account
other-types brokerage-account-to-user-account
other-types user-account-to-brokerage-account
other-types exchange-operation-to-user
other-types operations-account-earning
other-types market-account-to-user-account
other-types user-account-to-market-account
other-types trade-account-to-user-account
other-types user-account-to-trade-account
other-types backup-account-to-user-account
other-types user-account-to-backup-account
other-types fork-transfer-in
other-types fork-transfer-out
other-types point-purchased-gift
other-types matching-fee-brokerage
other-types matching-fee-brokerage-point
other-types api-matching-fee-brokerage
other-types api-matching-fee-brokerage-point
other-types matching-fee-cashback
other-types matching-fee-cashback-point
other-types exchange-fee-to-user
other-types otc-adjust-account-in
other-types otc-adjust-account-out
other-types otc-adjust-transfer-in
other-types otc-adjust-transfer-out
other-types option-liquidity-borrow
other-types option-liquidity-refund
other-types option-liquidity-other-borrow
other-types option-liquidity-other-refund
other-types linear-swap-liquidity-borrow
other-types linear-swap-liquidity-refund
other-types linear-swap-liquidity-other-borrow
other-types linear-swap-liquidity-other-refund
other-types otc-options-principal-clct-to-user-asset-ops-v3
other-types otc-options-income-to-user-asset-ops-manual
other-types otc-options-user-asset-ops-to-income-manual
other-types finance-clear-spot-to-sys-usa-jp
other-types finance-clear-sys-to-spot-usa-jp
other-types change-coin-chain-spot-to-sys
other-types change-coin-chain-sys-to-spot
other-types huoban-fund-spot-to-sys
other-types huoban-fund-sys-to-spot
other-types huoban-fund-interest-spot-to-sys
other-types head-hunting-sys-to-spot
other-types project-activity-spot-to-sys
other-types project-activity-sys-to-spot
other-types operation-to-super-margin-trade
other-types super-margin-trade-to-operation

Get Account Ledger

API Key Permission：Read

This endpoint returns the amount changes of specified user's account.

Phase 1 release only supports historical assets transfer querying ("transactType" = "transfer").

The maximum query window size set by "startTime" & "endTime" is 10-day, which mean a maximum of 10-day records are queriable per request. The query window can be within the last 180 days, which means, by adjusting "startTime" & "endTime" accordingly, the records in last 180 days are queriable.

HTTP Request

Request Parameters

Field Name Data Type Required Description
accountId string TRUE Account ID
currency string FALSE Cryptocurrency (default value: all)
transactTypes string FALSE Transaction types (multiple inputs are allowed; default value: all; enumerated values: transfer)
startTime long FALSE Farthest time (please refer to note 1 for valid range and default value)
endTime long FALSE Nearest time (please refer to note 2 for valid range and default value)
sort string FALSE Sorting order (enumerated values: asc, desc)
limit int FALSE Maximum number of items in one page (valid range:[1-500]; default value:100)
fromId long FALSE First record ID in this query (only valid for next page querying. please refer to note 3)

Note 1:
startTime valid range: [(endTime – 10days), endTime], unix time in millisecond
startTime default value: (endTime – 10days)

Note 2:
endTime valid range: [(current time – 180days), current time], unix time in millisecond
endTime default value: current time

The above command returns JSON structured like this:

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "accountId": 10000001,
            "currency": "usdt",
            "transactAmt": 10.000000000000000000,
            "transactType": "transfer",
            "transferType": "margin-transfer-out",
            "transactId": 0,
            "transactTime": 1629882331066,
            "transferer": 28483123,
            "transferee": 13496526
        },
        {
            "accountId": 10000001,
            "currency": "usdt",
            "transactAmt": -10.000000000000000000,
            "transactType": "transfer",
            "transferType": "margin-transfer-in",
            "transactId": 0,
            "transactTime": 1629882096562,
            "transferer": 13496526,
            "transferee": 28483123
        }
    ],
    "nextId": 1624316679,
    "ok": true
}

Response Content

Field Name Data Type Required Description Value Rage
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE Sorting as user defined (in request parameter "sort" )
accountId integer TRUE Account ID
currency string TRUE Cryptocurrency
transactAmt number TRUE Transaction amount (income positive, expenditure negative)
transactType string TRUE Transaction type
transferType string FALSE Transfer type (only valid for transactType=transfer) otc-to-pro, pro-to-otc, futures-to-pro, pro-to-futures, dm-swap-to-pro (coin-margined-swap), dm-pro-to-swap (coin-margined-swap), margin-transfer-in, margin-transfer-out, lock-transfer-in, lock-transfer-out, user-lock-transfer-in, user-lock-transfer-out, master-transfer-in, master-transfer-out, sub-transfer-in, sub-transfer-out, agency-transfer-in, agency-transfer-out, pro-to-super-margin, super-margin-to-pro
transactId integer TRUE Transaction ID
transactTime integer TRUE Transaction time
transferer integer FALSE Transferer’s account ID
transferee } integer FALSE Transferee’s account ID
</data>
nextId integer FALSE First record ID in next page (only valid if exceeded page size. please refer to note 3.)

Note 3:
Only when the number of items within the query window (between "startTime" and "endTime") exceeded the page limitation (defined by "limit"), Huobi server returns "nextId". Once received "nextId", API user should –
1) Be aware of that, some items within the query window were not returned due to the page size limitation.
2) In order to get these items from Huobi server, adopt the "nextId" as "fromId" and submit another request, with other request parameters no change.
3) As database record ID, "nextId" and "fromId" are for recurring query purpose and the ID itself does not have any business implication.

Transfer Fund Between Spot Account and Future Contract Account

API Key Permission：Trade

This endpoint allows a user to transfer fund between spot accounts and futrue contract accounts.

Transferring from a spot account to a contract account, the type is pro-to-futures; transferring from a contract account to a spot account, the type is futures-to-pro

HTTP Request

Request

{
  "currency": "btc",
  "amount": 0.001,
  "type": "pro-to-futures"
}

Request Parameters

Parameter Data Type Required Description Values
currency TRUE String Currency name Refer to GET /v1/common/currencys
amount TRUE Decimal Amount of fund to transfer
type TRUE String Type of the transfer "futures-to-pro" or "pro-to-futures"

Response:


{  
  "data": 12345,
  "status": "ok"
}

> Error response:
{
    "status": "error",
    "data": null,
    "err-code": "base-msg",
    "err-msg": "Insufficient amount available."
}

Response Content

Field Data Type Description
data Long Transfer id
status string Request status. "ok" or "error"
err-code string error code. Please refer to the err-code list below for details
err-msg string error message. Please refer to the err-code and err-msg list below for details

error code

err-code err-msg Comments
base-msg Other errors, please refer to err-msg list below for details.
base-currency-error The currency is invalid
frequent-invoke the operation is too frequent. Please try again later Rate limit is 10/min
banned-by-blacklist Blacklist restriction
dw-insufficient-balance Insufficient balance. You can only transfer {0} at most. Insufficient balance of spot account
dw-account-transfer-unavailable account transfer unavailable This API endpoint is not available.
dw-account-transfer-error account transfer error
dw-account-transfer-failed Failed to transfer. Please try again later.
dw-account-transfer-failed-account-abnormality Account abnormality, failed to transfer。Please try again later.

error message for 'base-msg' err-code

err-code err-msg Comments
base-msg Unable to transfer in currently. Please contact customer service.
base-msg Unable to transfer out currently. Please contact customer service.
base-msg Abnormal contracts status. Can’t transfer.
base-msg Sub-account doesn't own the permissions to transfer in. Please contact customer service.
base-msg Sub-account doesn't own the permissions to transfer out. Please contact customer service.
base-msg The sub-account does not have transfer permissions. Please login main account to authorize.
base-msg Insufficient amount available. Insufficient amount of Future Contract Account
base-msg The single transfer-out amount must be no less than {0}{1}.
base-msg The single transfer-out amount must be no more than {0}{1}.
base-msg The single transfer-in amount must be no less than {0}{1}.
base-msg The single transfer-in amount must be no more than {0}{1}.
base-msg Your accumulative transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
base-msg Your accumulative transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
base-msg Your accumulative net transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
base-msg Your accumulative net transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
base-msg The platform's accumulative transfer-out amount is over the daily maximum. You can't transfer out for the time being.
base-msg The platform's accumulative transfer-in amount is over the daily maximum. You can't transfer in for the time being.
base-msg The platform's accumulative net transfer-out amount is over the daily maximum. You can't transfer out for the time being.
base-msg The platform's accumulative net transfer-in amount is over the daily maximum. You can't transfer in for the time being.
base-msg Transfer failed. Please try again later or contact customer service.
base-msg Abnormal service, transfer failed. Please try again later.
base-msg You don’t have access permission as you have not opened contracts trading.
base-msg This contract type doesn't exist. There is no corresponding Future Contract for the currency defined in the request.

Get Point Balance

Via this endpoint, user should be able to query ‘termless’ point’s balance, as well as ‘terminable’ point’s balance including its group IDs and individual expiration date.
Via this endpoint, user could only query point’s balance instead of any other cryptocurrency’s balance.
Via this endpoint, parent user could query either parent user’s point balance, or sub user’s point balance.
User can only exchange Huobi point via Huobi official web or app.

API Key Permission：Read
Rate Limit: 2times/s
Callable by sub user

HTTP Request

Request Parameters

Field Data Type Required Description
subUid string FALSE Sub user’s UID (only valid for scenario of parent user querying sub user’s point balance)

Response:

{
    "code": 200,
    "data": {
        "accountId": "14403739",
        "groupIds": [
            {
                "groupId": 26,
                "expiryDate": 1594396800000,
                "remainAmt": "0.3"
            }
        ],
        "acctBalance": "0.30000000",
        "accountStatus": "working"
    },
    "success": true
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
success boolean TRUE
<data> object TRUE
accountId string TRUE Account ID
accountStatus string TRUE Account status (working, lock, fl-sys, fl-mgt, fl-end, fl-negative)
acctBalance string TRUE Account balance
<groupIds> object TRUE Group ID list
groupId long TRUE Group ID
expiryDate long TRUE Expiration date (unix time in millisecond)
remainAmt string TRUE Remaining amount
</groupIds>
</data>

Note:
Group ID is the transaction ID generated while parent user exchanging the ‘terminable’ points.
Group ID of ‘termless’ points is 0.
Expiration date of ‘termless’ points is null.

Point Transfer

Via this endpoint, parent user should be able to transfer points between parent user and sub user, sub user should be able to transfer point to parent user. Both ‘termless’ and ‘terminable’ points are transferrable.
Via this endpoint, user could only transfer ‘termless’ and ‘terminable’ points instead of any other cryptocurrencies.
Parent user could transfer point between parent user and sub user in two ways.
Sub user could only transfer point from sub user to parent user.
Before parent user trying to transfer the terminable points back from sub user's account, parent user should query the sub user's point balance first in order to get the corresponding groupId.

API Key Permission：Trade
Rate Limit: 2times/s
Callable by sub user

HTTP Request

Request Parameters

Field Data Type Required Description
fromUid string TRUE Transferer’s UID
toUid string TRUE Transferee’s UID
groupId long TRUE Group ID
amount string TRUE Transfer amount (precision: maximum 8 decimal places)

Note:
- If groupId=0, it implicates an ‘termless’ point transfer request.

Response:

{
    "code": 200,
    "data": {
        "transactId": "74",
        "transactTime": 1594370136458
    },
    "success": true
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
success boolean TRUE
<data> object TRUE
transactId string TRUE Transaction ID
transactTime long TRUE Transaction time (unix time in millisecond)
</data>

Error Code

Below is the error code, error message and description returned by Account APIs.

Error Code Error Message Description
500 system error Server internal error
1002 forbidden Operation is forbidden, such as the account Id and UID doesn't match
2002 "invalid field value in currency" Parameter currency is invalid
2002 "invalid field value in transactTypes" Parameter transactTypes is invalid (should be transfer)
2002 "invalid field value in sort" Parameter sort is invalid (should be 'asc' or 'desc')
2002 "value in fromId is not found in record" Value fromId doesn't exist
2002 "invalid field value in accountId" Parameter accountId is invalid (should not be empty)
2002 "value in startTime exceeded valid range" Value startTime is later than current time or earlier than 180 days ago
2002 "value in endTime exceeded valid range") Value endTime is earlier than startTime, or 10 days later than startTime

Wallet (Deposit and Withdraw)

Introduction

Wallet APIs provide query functionality for deposit address, withdraw address, withdraw quota, deposit and withdraw history, and also provide withdraw and cancel-withdraw functionality.

Query Deposit Address

Parent user and sub user could query deposit address of corresponding chain, for a specific crypto currency (except IOTA).

API Key Permission：Read
Rate Limit (NEW): 20times/2s

HTTP Request

Request Parameters

Field Name Data Type Required Default Value Description
currency string true N/A Crypto currency,refer to GET /v1/common/currencys

The above command returns JSON structured like this:

{
    "code": 200,
    "data": [
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "0xd476b0d77583fbda5180039f1f513b750cb4f527",
            "addressTag": "",
            "chain": "hbtc"
        },
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "16egzDeZiVDJ4D44UbWKN6snLYFjS1aEmJ",
            "addressTag": "",
            "chain": "btc"
        },
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "0xd476b0d77583fbda5180039f1f513b750cb4f527",
            "addressTag": "",
            "chain": "hrc20btc"
        }
    ]
}

Response Content

Field Name Data Type Description
code int Status code
message string Error message (if any)
<data> object
currency string Crypto currency
address string Deposit address
addressTag string Deposit address tag
chain string Block chain name
</data>

Query Withdraw Quota

Parent user could query withdrawing quota for currencies

API Key Permission：Read
Rate Limit (NEW): 20times/2s

HTTP Request

Request Parameters

Field Name Data Type Required Default Value Description
currency string true N/A Crypto currency,refer to GET /v1/common/currencys

The above command returns JSON structured like this:

{
    "code": 200,
    "data": {
        "currency": "usdt",
        "chains": [
            {
                "chain": "hrc20usdt",
                "maxWithdrawAmt": "2000000.000000000000000000",
                "withdrawQuotaPerDay": "4845303.99999991",
                "remainWithdrawQuotaPerDay": "4845303.99999991",
                "withdrawQuotaPerYear": "-1",
                "remainWithdrawQuotaPerYear": "-1",
                "withdrawQuotaTotal": "-1",
                "remainWithdrawQuotaTotal": "-1"
            },
            {
                "chain": "trc20usdt",
                "maxWithdrawAmt": "1000000.000000000000000000",
                "withdrawQuotaPerDay": "4845303.99999991",
                "remainWithdrawQuotaPerDay": "4845303.99999991",
                "withdrawQuotaPerYear": "-1",
                "remainWithdrawQuotaPerYear": "-1",
                "withdrawQuotaTotal": "-1",
                "remainWithdrawQuotaTotal": "-1"
            },
            {
                "chain": "usdt",
                "maxWithdrawAmt": "600000.000000000000000000",
                "withdrawQuotaPerDay": "4845303.99999991",
                "remainWithdrawQuotaPerDay": "4845303.99999991",
                "withdrawQuotaPerYear": "-1",
                "remainWithdrawQuotaPerYear": "-1",
                "withdrawQuotaTotal": "-1",
                "remainWithdrawQuotaTotal": "-1"
            },
            {
                "chain": "usdterc20",
                "maxWithdrawAmt": "1000000.000000000000000000",
                "withdrawQuotaPerDay": "4845303.99999991",
                "remainWithdrawQuotaPerDay": "4845303.99999991",
                "withdrawQuotaPerYear": "-1",
                "remainWithdrawQuotaPerYear": "-1",
                "withdrawQuotaTotal": "-1",
                "remainWithdrawQuotaTotal": "-1"
            }
        ]
    }
}

Response Content

Field Name Data Type Description
code int Status code
message string Error message (if any)
<data> object
currency string Crypto currency
<chains> object
chain string Block chain name
maxWithdrawAmt string Maximum withdraw amount in each request
withdrawQuotaPerDay string Maximum withdraw amount in a day
remainWithdrawQuotaPerDay string Remaining withdraw quota in the day
withdrawQuotaPerYear string Maximum withdraw amount in a year
remainWithdrawQuotaPerYear string Remaining withdraw quota in the year
withdrawQuotaTotal string Maximum withdraw amount in total
remainWithdrawQuotaTotal string Remaining withdraw quota in total
</chains>
</data>

Query withdraw address

API Key Permission: Read

This endpoint allows parent user to query withdraw address available for API key.

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Value Range
currency true string Crypto currency btc, ltc, bch, eth, etc ...(refer to GET /v1/common/currencys)
chain false string Block chain name When chain is not specified, the reponse would include the records of ALL chains.
note false string The note of withdraw address When note is not specified, the reponse would include the records of ALL notes.
limit false int The number of items to return 100 [1-500]
fromId false long First record ID in this query (only valid for next page querying; please refer to note) NA

Response:

{
    "code": 200,
    "data": [
        {
            "currency": "usdt",
            "chain": "hrc20usdt",
            "note": "tom",
            "addressTag": "",
            "address": "0x3b994f25c4c25e99d4d26364ffc014cce64600ca"
        }
    ],
    "next-id": 30137790
}

Response Content

Field Name Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
currency true string Crypto currency
chain true string Block chain name
note true string The address note
addressTag false string The address tag，if any
address true string Withdraw address
</data>
nextId false long First record ID in next page (only valid if exceeded page size)

Note:
Only when the number of items within the query window exceeded the page limitation (defined by "limit"), Huobi server returns "nextId". Once received "nextId", API user should –
1) Be aware of that, some items within the query window were not returned due to the page size limitation.
2) In order to get these items from Huobi server, adopt the "nextId" as "fromId" and submit another request, with other request parameters no change.
3) "nextId" and "fromId" are for recurring query purpose and the ID itself does not have any business implication.

Create a Withdraw Request

API Key Permission：Withdraw
Rate Limit (NEW): 20times/2s

Parent user creates a withdraw request from spot account to an external address (exists in your withdraw address list), which doesn't require two-factor-authentication.

HTTP Request

Request:

{
  "address": "0xde709f2102306220921060314715629080e2fb77",
  "amount": "0.05",
  "currency": "eth",
  "fee": "0.01"
}

Request Parameters

Parameter Data Type Required Default Description
address string true NA The desination address of this withdraw
currency string true NA Crypto currency,refer to GET /v1/common/currencys
amount string true NA The amount of currency to withdraw
fee float false NA >=0,Please check whether the handling fee is too high through the handling fee interface before withdrawal to avoid losses, and cancel the operation through the "Cancel the Withdrawal" interface before successful withdrawal
chain string false NA Refer toGET /v2/reference/currencies.Set as "usdt" to withdraw USDT to OMNI, set as "trc20usdt" to withdraw USDT to TRX
addr-tag string false NA A tag specified for this address
client-order-id string false NA client order id

Note

The above command returns JSON structured like this:

{  
  "data": 1000
}

Response Content

Field Data Type Description
data integer Transfer id

Query withdrawal order by client order id

API Key Permission: Read

HTTP Request

Request Parameters

Parameter Required Data Type Description Value Range
clientOrderId true string client order id (max 32 char)

Note

Response:


 {
    "status": "ok",
    "data": {
        "id": 101123262,
        "client-order-id": "1113",
        "type": "withdraw",
        "sub-type": "FAST",
        "currency": "usdt",
        "chain": "usdt",
        "tx-hash": "",
        "amount": 1.200000000000000000,
        "from-addr-tag": "",
        "address": "1PL24EbWrNNrnMKw1cxAHPsebUz7DdhWTx",
        "address-tag": "",
        "fee": 0E-18,
        "state": "confirmed",
        "created-at": 1637758163686,
        "updated-at": 1637758251559
    }
}

响应数据

Parameter Required Data Type Description Value Range
status > true stirng status code
<data\ > false long
address true string address
client-order-id true string client order id
address-tag true string address tag
amount true decimal amount
blockchain-confirm false int the number of blockchain confirmations
chain false string chain
created-at true long created at
currency true string currency
error-code true string error code
error-msg true string error msg
fee true decimal fee
from-addr-tag true string from address tag
from-address false string from address
id true long ID
request-id true string request id
state true string state
tx-hash true string transmit hash
type true string type
updated-at true long updated at
user-id false long user id
wallet-confirm false int the number of wallet confirmations
</data> false long

Cancel a Withdraw Request

API Key Permission：Withdraw
Rate Limit (NEW): 20times/2s

Parent user cancels a previously created withdrawal request by its transfer id.

HTTP Request

'withdraw-id': the id returned when previously created a withdraw request

Request Parameters

The above command returns JSON structured like this:

{
  "data": 700
}

Response Content

Parameter Data Type Description
data integer Withdraw cancel id

Search for Existed Withdraws and Deposits

API Key Permission：Read
Rate Limit (NEW): 20times/2s

Parent user and sub user search for all existed withdraws and deposits and return their latest status.

HTTP Request

Request Parameters

Parameter Data Type Required Description Value Range Default Value
currency string false The crypto currency to withdraw NA When currency is not specified, the response would include the records of ALL currencies.
type string true Define transfer type to search deposit, withdraw, sub user can only use deposit
from string false The transfer id to begin search 1 ~ latest record ID When 'from' is not specified, the default value would be 1 if 'direct' is 'prev' with the response in ascending order, the default value would be the ID of latest record if 'direct' is 'next' with the response in descending order.
size string false The number of items to return [1-500] 100
direct string false the order of response 'prev' (ascending), 'next' (descending) 'prev'

The above command returns JSON structured like this:

{
    "status":"ok",
    "data":[
        {
            "id":45182894,
            "type":"withdraw",
            "sub-type":"FAST",
            "currency":"usdt",
            "chain":"trc20usdt",
            "tx-hash":"",
            "amount":400,
            "from-addr-tag":"",
            "address":"TRwkUYHWgUh23jbKpgTcYHgE9CcBzhGno9",
            "address-tag":"",
            "fee":0,
            "state":"confirmed",
            "created-at":1612261330443,
            "updated-at":1612261389250
        },
        {
            "id":61003926,
            "type":"withdraw",
            "sub-type":"FAST",
            "currency":"usdt",
            "chain":"trc20usdt",
            "tx-hash":"",
            "amount":2,
            "from-addr-tag":"",
            "address":"TYGvZSD1duPctGaMPSP12Fy8BrQMu2KCdp",
            "address-tag":"",
            "fee":0,
            "state":"confirmed",
            "created-at":1621416907639,
            "updated-at":1621416907788
        }
    ]
}

Response Content

Field Data Type Description
status string Request Processing Result
<data> object
id integer Transfer id
type string Define transfer type to search, possible values: [deposit, withdraw] Sub-user can only put "deposit"
currency string The crypto currency to withdraw
tx-hash string The on-chain transaction hash. If this is a "fast withdraw", then it is not on-chain transfer, and this value is empty.
chain string Block chain name
amount float The number of crypto asset transfered in its minimum unit
address string The deposit or withdraw target address
address-tag string The user defined address tag
fee float Withdrawal fee
state string The state of this transfer (see below for details)
error-code string Error code for withdrawal failure, only returned when the type is "withdraw" and the state is "reject", "wallet-reject" and "failed".
error-msg string Error description of withdrawal failure, only returned when the type is "withdraw" and the state is "reject", "wallet-reject" and "failed".
created-at integer The timestamp in milliseconds for the transfer creation
updated-at integer The timestamp in milliseconds for the transfer's latest update
</data>

List of possible deposit state

State Description
unknown On-chain transfer has not been received
confirming On-chain transfer waits for first confirmation
confirmed On-chain transfer confirmed for at least one block, user is able to transfer and trade
safe Multiple on-chain confirmed, user is able to withdraw
orphan On-chain transfer confirmed but currently in an orphan branch

List of possible withdraw state

State Description
verifying Awaiting verification
failed verification failed
submitted Withdraw request submitted successfully
reexamine Under examination for withdraw validation
canceled Withdraw canceled by user
pass Withdraw validation passed
reject Withdraw validation rejected
pre-transfer Withdraw is about to be released
wallet-transfer On-chain transfer initiated
wallet-reject Transfer rejected by chain
confirmed On-chain transfer completed with one confirmation
confirm-error On-chain transfer faied to get confirmation
repealed Withdraw terminated by system

Error Code

Below is the response code, message and description returned by Wallet APIs.

Response Code Message Description
200 success Successful
500 error Server internal error
1002 unauthorized User is unautherized
1003 invalid signature API signature is wrong
2002 invalid field value in "field name" Parameter is invalid
2003 missing Required field "field name" Parameter is missing

FAQ

Q1：Why the API returns error 'api-not-support-temp-addr' when withdrawing?

A：User has to include the address into the pre-defined address table on Huobi official website before withdrawing through API.

Q2：Why the API returns error 'Invaild-Address' when withdraw USDT?

A：USDT locates on multiple chains, therefore the withdraw order should clearly specify which chain the withdrawal goes to. See the table below:

Chain Field Value
ERC20 (default) usdterc20
OMNI usdt
TRX trc20usdt

If leaving the field empty, default target chain is ERC20, or you can explicitly set the chain to usdterc20.

If the target chain is OMNI or TRX, the field value should be usdt or trc20usdt.

The full chain name list for all currencies can be retrieved from endpoint GET /v2/reference/currencies.

Q3：How to specify 'fee' when creating a withdraw request?

A：Please refer to the response from endpoint GET /v2/reference/currencies, where the field withdrawFeeType defining different fee types below:

Q4：How to query my withdraw quota?

A：Please refer to the response from endpoint GET /v2/account/withdraw/quota, where quota per request, daily quota, annual quota, overall quota are available.

Note: If you need to withdraw large amount which breaking the limitation, you can contact customer support for assistance.

Sub user management

Introduction

Sub user management APIs provide sub user account management (creation, query, permission, transfer), sub user API key management (creation, update, query, deletion), sub user address (deposit, withdraw) query and balance query.

Set a deduction for parent and sub user

This interface is to set the deduction fee for parent and sub user (HT or point ).

API Key Permission：Trade

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Range
subUids true long Sub user's UID list (maximum 50 UIDs, separated by comma) NA
deductMode true string deduct mode：master ,sub NA

Response:

{
    "code": 200,
    "data": [
        {
            "subUid": "158069153",
            "deductMode": "master"
        },
        {
            "subUid": "1461901631",
            "deductMode": null,
            "errCode": 1002,
            "errMessage": "forbidden"
        }
    ],
    "ok": true
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
subUid true string Sub user's UID
deductMode true string deduct mode
errCode true string Error code in case of rejection (only valid when the requested UID being rejected)
errMessage false string Error message in case of rejection (only valid when the requested UID being rejected)
</data>

API key query

This endpoint is used by the parent user to query their own API key information, and the parent user to query their sub user's API key information.

API Key Permission：Read

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Range
uid true long parent user uid , sub user uid NA
accessKey false string The access key of the API key, if not specified, it will return all API keys belong to the UID. NA

Response:

{
    "code":200,
    "message":"success",
    "data":[
        {
            "accessKey":"160bb889-b7XXXXbe-e0XXXXf5-ghxertfvbf",
            "status":"normal",
            "note":"host",
            "permission":"trade,readOnly",
            "ipAddresses":"192.168.0.1,192.168.1.1",
            "validDays":-1,
            "createTime":1615192704000,
            "updateTime":1623030338000
        },
        {
            "accessKey":"5000d371-edXXXXf5tf-40XXXX8b-ab8e5",
            "status":"normal",
            "note":"host two",
            "permission":"readOnly,trade,withdraw",
            "ipAddresses":"",
            "validDays":7,
            "createTime":1623158078000,
            "updateTime":1629875976000
        }
    ],
    "ok":true
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
accessKey true string access key
note true string API key note
permission true string API key permission
ipAddresses true string API key IP addresses
validDays true int API key expire in (days) If it is -1, it means permanently valid
status true string API key status normal, expired
createTime true long API key creation time
updateTime true long API key last modified time
</data>

Get UID

This endpoint allow users to view the user ID of the account easily.

API Key Permission：Read

HTTP Request

Request Parameters

No parameters are needed for this endpoint.

Response:

{
    "code": 200,
    "data": 63628520
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
data true long UID

Sub user creation

This endpoint is used by the parent user to create sub users, up to 50 at a time

API Key Permission：Trade

HTTP Request

Request:

{
    "userList":[
        {
            "userName":"test123",
            "note":"huobi"
        },
        {
            "userName":"test456",
            "note":"huobi two"
        }
    ]
}

Request Parameters

Parameter Required Data Type Description Default Value Range
<userList> true object
userName true string Sub user name, an important identifier of the sub user's identity, requires unique within the huobi platform NA The combination of 6 to 20 letters and numbers, or only letters. Letter is not case sensitive. The first character has to be a letter.
note false string Sub user note, no unique requirements NA Up to 20 characters, unlimited character types
</userList>

Response:

{
    "code":200,
    "data":[
        {
            "userName":"test123",
            "note":"huobi",
            "uid":123
        },
        {
            "userName":"test456",
            "note":"huobi two",
            "errCode":"2002",
            "errMessage":"value in user name duplicated with existing record"
        }
    ]
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
userName true string Sub user name
note false string Sub user note (only valid for sub-users with note)）
uid false long Sub user UID (only valid for successfully created sub users)
errCode false string Error code for creation failure (only valid for sub users that failed to create)
errMessage false string Cause of creation failure error (only valid for sub users that failed to create)
</data>

Get Sub User's List

Via this endpoint parent user is able to query a full list of sub user's UID as well as their status.

API Key Permission: Read

HTTP Request

Request Parameter

Field Required Data Type Description Default Value Possible Value
fromId FALSE long First record ID in next page (only valid if exceeded page size)

Response:

{
    "code": 200,
    "data": [
        {
            "uid": 63628520,
            "userState": "normal"
        },
        {
            "uid": 132208121,
            "userState": "normal"
        }
    ]
}

Response

Field Required Data Type Description Possible Value
code TRUE int Status code
message FALSE string Error message (if any)
<data> TRUE object In ascending order of uid, each response contains maximum 100 records
uid TRUE long Sub user’s UID
userState TRUE string Sub user’s status lock, normal
</data>
nextId FALSE long First record ID in next page (only valid if exceeded page size)

Lock/Unlock Sub User

API Key Permission：Trade
Rate Limit (NEW): 20times/2s

This endpoint allows parent user to lock or unlock a specific sub user.

HTTP Request

Request Parameters

Parameter Data Type Required Description Value Range
subUid long true Sub user UID NA
action string true Action type lock,unlock

The above command returns JSON structured like this:

{
    "code": 200,
    "data": {
        "subUid": 245686628,
        "userState": "lock"
    },
    "ok": true
}

Response Content

Field Data Type Description Value Range
code true int status code
<data> true object
subUid long sub user UID NA
userState string The state of sub user lock,normal
</data>

Get Sub User's Status

Via this endpoint, parent user is able to query sub user's status by specifying a UID.

API Key Permission: Read

HTTP Request

Request Parameter

Field Required Data Type Description Default Value Possible Value
subUid TRUE long Sub user's UID

Response:

{
    "code": 200,
    "data": {
        "uid": 132208121,
        "userState": "normal"
    }
}

Response

Field Required Data Type Description Possible Value
code TRUE int Status code
message FALSE string Error message (if any)
<data> TRUE object
uid TRUE long Sub user’s UID
userState TRUE string Sub user’s status lock, normal
</data>

Set Tradable Market for Sub Users

API Key Permission: Trade

Parent user is able to set tradable market for a batch of sub users through this endpoint. By default, sub user’s trading permission in spot market is activated.

HTTP Request

Request Parameters

Parameter Required Data Type Length Description Possible Value
subUids true string - Sub user's UID list (maximum 50 UIDs, separated by comma) -
accountType true string - Account type isolated-margin,cross-margin
activation true string - Account activation activated,deactivated

Response:

{
    "code": 200,
    "data": [
        {
            "subUid": "12345678",
            "accountType": "isolated-margin",
            "activation": "activated"
        },
        {
            "subUid": "123456781",
            "accountType": "isolated-margin",
            "errCode": 1002,
            "errMessage": "forbidden"
        }
    ],
    "ok": true
}

Response Content

Parameter Required Data Type Length Description Possible Value
code true int - Status code
message false string - Error message (if any)
<data> true object
subUid true string - Sub user's UID -
accountType true string - Account type isolated-margin,cross-margin
activation true string - Account activation activated,deactivated
errCode false int - Error code in case of rejection (only valid when the requested UID being rejected)
errMessage false string - Error message in case of rejection (only valid when the requested UID being rejected)
</data>

Set Asset Transfer Permission for Sub Users

API Key Permission: Trade

Parent user is able to set asset transfer permission for a batch of sub users. By default, the asset transfer from sub user’s spot account to parent user’s spot account is allowed.

HTTP Request

Request Parameters

Parameter Required Data Type Length Description Possible Value
subUids true string - Sub user's UID list (maximum 50 UIDs, separated by comma) -
accountType false string - Account type (if not available, adopt default value 'spot'） spot
transferrable true bool - Transferrablility true,false

Response:

{
    "code": 200,
    "data": [
        {
            "accountType": "spot",
            "transferrable": true,
            "subUid": 245686628
        },
        {
            "accountType": "spot",
            "subUid": 2215699261,
            "errCode": 2002,
            "errMessage": "invalid field value in `2,215,699,261`"
        }
    ],
    "ok": true
}

Response Content

Parameter Required Data Type Length Description Possible Value
code true int - Status code
message false string - Error message (if any)
<data> true object
subUid true long - Sub user's UID -
accountType true string - Account type spot
transferrable true bool - Transferrability true,false
errCode false int - Error code in case of rejection (only valid when the requested UID being rejected)
errMessage false string - Error code in case of rejection (only valid when the requested UID being rejected)
</data>

Get Sub User's Account List

Via this endpoint parent user is able to query account list of sub user by specifying a UID.

API Key Permission: Read

HTTP Request

Request Parameter

Field Required Data Type Description Default Value Possible Value
subUid TRUE long Sub User's UID

Response:

{
    "code": 200,
    "data": {
        "uid": 132208121,
        "deductMode": "sub",
        "list": [
            {
                "accountType": "isolated-margin",
                "activation": "activated"
            },
            {
                "accountType": "cross-margin",
                "activation": "deactivated"
            },
            {
                "accountType": "spot",
                "activation": "activated",
                "transferrable": true,
                "accountIds": [
                    {
                        "accountId": 12255180,
                        "accountStatus": "normal"
                    }
                ]
            }
        ]
    }
}

Response

Field Required Data Type Description Possible Value
code TRUE int Status code
message FALSE string Error message (if any)
<data> TRUE object
uid TRUE long Sub user’s UID
deductMode TRUE string deduct mode
<list> TRUE object
accountType TRUE string Account type spot, isolated-margin, cross-margin, futures,swap
activation TRUE string Account’s activation activated, deactivated
transferrable FALSE bool Transfer permission (only valid for accountType=spot) true, false
<accountIds> FALSE object
accountId TRUE string Account ID
subType FALSE string Account sub type (only valid for accountType=isolated-margin)
accountStatus TRUE string Account status normal, locked
</accountIds>
</list>
</data>

Sub user API key creation

This endpoint is used by the parent user to create the API key of the sub user

API Key Permission：Trade

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Range
otpToken false string Google verification code of the parent user, the parent user must be bound to Google Authenticator for verification on the web NA 6 characters, pure numbers
subUid true long Sub user UID NA
note true string API key note NA Up to 255 characters with any font
permission true string API key permissions NA Valid value: readOnly, trade; multiple inputs are allowed, separated by comma, i.e. readOnly, trade; readOnly is required permission for any API key, while trade permission is optional.
ipAddresses false string The IPv4/IPv6 host address or IPv4 network address bound to the API key NA At most 20 IPv4/IPv6 host address(es) and/or IPv4 network address(es) can bind with one API key, separated by comma. For example: 202.106.196.115, 202.106.96.0/24. An API key not linked with an IP address but has trading or withdrawal permissions will be automatically deactivated after 90 days of inactivity.

Response:

{
    "code": 200,
    "data": {
        "accessKey": "2b55df29-vf25treb80-1535713d-8aea2",
        "secretKey": "c405c550-6fa0583b-fb4bc38e-d317e",
        "note": "62924133",
        "permission": "trade,readOnly",
        "ipAddresses": "192.168.0.1,192.168.1.1"
    }
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
note true string API key note
accessKey true string access key
secretKey true string secret key
permission true string API key permission
ipAddresses true string API key IP addresses
</data>

Sub user API key modification

This endpoint is used by the parent user to modify the API key of the sub user

API Key Permission：Trade

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Range
subUid true long sub user uid NA
accessKey true string Access key for sub user API key NA
note false string API key note for sub user API key NA Up to 255 characters
permission false string API key permission for sub user API key NA Valid value: readOnly, trade; multiple inputs are allowed, separated by comma, i.e. readOnly, trade; readOnly is required permission for any API key, while trade permission is optional.
ipAddresses false string At most 20 IPv4/IPv6 host address(es) and/or IPv4 network address(es) can bind with one API key, separated by comma. For example: 202.106.196.115, 202.106.96.0/24. An API key not linked with an IP address but has trading or withdrawal permissions will be automatically deactivated after 90 days of inactivity. NA

Response:

{
    "code": 200,
    "data": {
        "note": "tom",
        "permission": "trade,readOnly",
        "ipAddresses": "192.168.1.1"
    },
    "ok": true
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)
<data> true object
{ note true string API key note
permission true string API key permission
ipAddresses true string IPv4/IPv6 host address(es) or IPv4 network address(es) bind to the API key
</data>

Sub user API key deletion

This endpoint is used by the parent user to delete the API key of the sub user.

API Key Permission：Trade

HTTP Request

Request Parameters

Parameter Required Data Type Description Default Value Range
subUid true long sub user uid NA
accessKey true string Access key for sub user API key NA

Response:

{
    "code": 200,
    "data": null
}

Response Content

Parameter Required Data Type Description Value Range
code true int Status code
message false string Error message (if any)）

Transfer Asset between Parent and Sub Account

API Key Permission：Trade
Rate Limit (NEW): 2times/2s

This endpoint allows user to transfer asset between parent and sub account.

HTTP Request

Request Parameters

Parameter Data Type Required Description Value Range
sub-uid integer true The sub account's uid to transfer to or from NA
currency string true The type of currency to transfer NA
amount decimal true The amount of asset to transfer NA
type string true The type of transfer master-transfer-in, master-transfer-out, master-point-transfer-in, master-point-transfer-out

The above command returns JSON structured like this:

{
  "data":123456,
  "status":"ok"
}

Response Content

Field Data Type Description
data integer Unique transfer id
status string status

Query Deposit Address of Sub User

Parent user could query sub user's deposit address on corresponding chain, for a specific crypto currency (except IOTA).

API Key Permission：Read

HTTP Request

Request Parameters

Field Name Data Type Required Default Value Description
subUid long true N/A Sub user UID (limited to 1 per request)
currency string true N/A Crypto currency,refer to GET /v1/common/currencys

The above command returns JSON structured like this:

{
    "code": 200,
    "data": [
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "0x4efee1ca7fc887d921f4bbcc444fbc12c464d87f",
            "addressTag": "",
            "chain": "hbtc"
        },
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "1C4o8WmACM8yHBbJjbdzLbc9ei7WFLFoMk",
            "addressTag": "",
            "chain": "btc"
        },
        {
            "userId": 12345678,
            "currency": "btc",
            "address": "0x4efee1ca7fc887d921f4bbcc444fbc12c464d87f",
            "addressTag": "",
            "chain": "hrc20btc"
        }
    ]
}

Response Content

Field Name Data Type Description
code int Status code
message string Error message (if any)
<data> object
currency string Crypto currency
address string Deposit address
addressTag string Deposit address tag
chain string Block chain name
</data>

Query Deposit History of Sub User

API Key Permission：Read

Parent user could query sub user's deposit history via this endpoint.

HTTP Request

Request Parameters

Field Name Data Type Required Description
subUid long ture Sub user UID
currency string FALSE Cryptocurrency (default value: all)
startTime long FALSE Farthest time (please refer to note 1 for valid range and default value)
endTime long FALSE Nearest time (please refer to note 2 for valid range and default value)
sort string FALSE Sorting order (enumerated values: asc, desc)
limit int FALSE Maximum number of items in one page (valid range:[1-500]; default value:100)
fromId long FALSE First record ID in this query (only valid for next page querying; please refer to note 3)

Note 1:
startTime valid range: [(endTime – 30days), endTime]
startTime default value: (endTime – 30days)

Note 2:
endTime valid range: Unlimited
endTime default value: current time

Note 3:
Only when the number of items within the query window (between "startTime" and "endTime") exceeded the page limitation (defined by "limit"), Huobi server returns "nextId". Once received "nextId", API user should –
1) Be aware of that, some items within the query window were not returned due to the page size limitation.
2) In order to get these items from Huobi server, adopt the "nextId" as "fromId" and submit another request, with other request parameters no change.
3) "nextId" and "fromId" are for recurring query purpose and the ID itself does not have any business implication.

The above command returns JSON structured like this:

{
    "code": 200,
    "data": [
        {
            "id": 33419472,
            "currency": "ltc",
            "chain": "ltc",
            "amount": 0.001000000000000000,
            "address": "LUuuPs5C5Ph3cZz76ZLN1AMLSstqG5PbAz",
            "state": "safe",
            "txHash": "847601d249861da56022323514870ddb96456ec9579526233d53e690264605a7",
            "addressTag": "",
            "createTime": 1587033225787,
            "updateTime": 1587033716616
        }
    ]
}

Response Content

Field Name Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE
id long TRUE Deposit id
currency string TRUE Cryptocurrency
txHash string TRUE The on-chain transaction hash
chain string TRUE Block chain name
amount float TRUE The number of crypto asset transferred
address string TRUE The deposit source address
addressTag string FALSE The user defined address tag
state string TRUE The state of this transfer (see below for details)
createTime long TRUE The timestamp in milliseconds for the transfer creation
updateTime long TRUE The timestamp in milliseconds for the transfer's latest update
</data>
nextId long FALSE First record ID in next page (only valid if exceeded page size)

List of possible deposit state

State Description
unknown On-chain transfer has not been received
confirming On-chain transfer waits for first confirmation
confirmed On-chain transfer confirmed for at least one block
safe Multiple on-chain confirmation happened
orphan Confirmed but currently in an orphan branch

Get the Aggregated Balance of all Sub-users

API Key Permission：Read
Rate Limit (NEW): 2times/2s

This endpoint returns the aggregated balance from all the sub-users.

HTTP Request

Request Parameters

Response Content

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "currency": "hbpoint",
            "balance": "10",
            "type": "point"
        },
        {
            "currency": "ada",
            "balance": "0",
            "type": "spot"
        },
        {
            "currency": "usdt",
            "balance": "8.08559165",
            "type": "spot"
        }
    ]
}

Response Parameters

Field Data Type Description
status true string
<data> true list
currency string The currency of this balance
type string account type (spot, margin, point,super-margin)
balance string The total balance in the main currency unit including all balance and frozen banlance
</data>

Get Account Balance of a Sub-User

API Key Permission：Read
Rate Limit (NEW): 20times/2s

This endpoint returns the balance of a sub-user specified by sub-uid.

HTTP Request

'sub-uid': The specified sub user id to get balance for.

Request Parameters

Field Name Data Type Required Description
sub-uid long ture Sub user UID

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "id": 13704588,
            "type": "spot",
            "state": "working",
            "list": [
                {
                    "currency": "usdt",
                    "type": "trade",
                    "balance": "8.0855916572"
                }
            ],
            "symbol": ""
        },
        {
            "id": 24994285,
            "type": "point",
            "state": "working",
            "list": [
                {
                    "currency": "hbpoint",
                    "type": "trade",
                    "balance": "10"
                }
            ],
            "symbol": ""
        }
    ]
}

Response Content

Field Description Data Type Value Range
status TRUE string status "OK" or "Error"
<data> TRUE object
id TRUE integer account's ID
type TRUE string The type of this account: spot, margin, otc, point,super-margin
<list> TRUE object
currency TRUE string The currency of this balance
type TRUE string The balance type: trade, frozen, loan, interest, lock, bank
balance TRUE string The balance in the main currency unit
</list>
symbol TRUE string
</data>

Error Code

Below is the error code, error message and description returned by Sub user management APIs

Error Code Error Message Description
1002 forbidden Operation is forbidden, such as sub user creation is not allowed for current user
1003 unauthorized Signature is wrong
2002 invalid field value Parameter is invalid
2014 number of sub account in the request exceeded valid range number of sub account exceeded
2014 number of api key in the request exceeded valid range number of API Key exceeded
2016 invalid request while value specified in sub user states lock or unlock failure

Trading

Introduction

Trading APIs provide trading related functionality, including placing order, canceling order, order history query, trading history query, transaction fee query.

Below is the glossary of trading related field:

order type: The order type is consist of trade direction and behavior type: [direction]-[type]

direction:

type:

order source: the origin of the order

order state:

IDs: The frequently used identities are listed below:

Place a New Order

API Key Permission：Trade
Rate Limit (NEW): 100times/2s

This endpoint places a new order and sends to the exchange to be matched.

HTTP Request

{
  "account-id": "100009",
  "amount": "10.1",
  "price": "100.1",
  "source": "spot-api",
  "symbol": "ethusdt",
  "type": "buy-limit",
  "client-order-id": "a0001"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
account-id string true NA The account id used for this trade Refer to GET /v1/account/accounts
symbol string true NA The trading symbol to trade Refer to GET /v1/common/symbols
type string true NA The order type buy-market, sell-market, buy-limit, sell-limit, buy-ioc, sell-ioc, buy-limit-maker, sell-limit-maker, buy-stop-limit, sell-stop-limit, buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok
amount string true NA order size (for buy market order, it's order value) NA
price string false NA The order price (not available for market order) NA
source string false spot-api When trade with spot use 'spot-api';When trade with isolated margin use 'margin-api'; When trade with cross margin use 'super-margin-api';When trade with c2c-margin use 'c2c-margin-api'; api, margin-api,super-margin-api,c2c-margin-api
client-order-id string false NA Client order ID (maximum 64-character length, to be unique within 8 hours)
self-match-prevent int false 0 self match prevent. 0: no, means allowing self-trading; 1: yes, means not allowing self-trading
stop-price string false NA Trigger price of stop limit order
operator string false NA operation charactor of stop price gte – greater than and equal (>=), lte – less than and equal (<=)

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": "356501383558845"
}

Response Content

If client order ID duplicates with a previous order (within 8 hours), the endpoint reverts error message invalid.client.order.id.

buy-limit-maker

If the order price is greater than or equal to the lowest selling price in the market, the order will be rejected.

If the order price is less than the lowest selling price in the market, the order will be accepted.

sell-limit-maker

If the order price is less than or equal to the highest buy price in the market, the order will be rejected.

If the order price is greater than the highest buy price in the market, the order will be accepted.

Place a Batch of Orders

API Key Permission：Trade
Rate Limit (NEW): 50times/2s

A batch contains at most 10 orders.

HTTP Request

[
    {
        "account-id": "13496526",
        "symbol": "adausdt",
        "type": "buy-limit-maker",
        "amount": "5",
        "price": "1",
        "source": "spot-api",
        "client-order-id": "2345"
    },
    {
        "account-id": "13496526",
        "symbol": "adausdt",
        "type": "buy-limit-maker",
        "amount": "4",
        "price": "1",
        "source": "spot-api","client-order-id": "23456"
    }
]

Request Parameters

Parameter Data Type Required Default Description
[{ account-id string true NA The account id, refer to GET /v1/account/accounts. Use 'spot' account-id for spot trading, use 'margin' account-id for isolated margin trading, use ‘super-margin’ account-id for cross margin trading. use borrow account id for c2c margin trading
symbol string true NA The trading symbol, i.e. btcusdt, ethbtc...(Refer to GET /v1/common/symbols)
type string true NA The type of order, including 'buy-market', 'sell-market', 'buy-limit', 'sell-limit', 'buy-ioc', 'sell-ioc', 'buy-limit-maker', 'sell-limit-maker' (refer to detail below), 'buy-stop-limit', 'sell-stop-limit', buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok.
amount string true NA The order size (for buy market order, it's order value)
price string false NA The order price (not available for market order)
source string false spot-api When trade with spot use 'spot-api';When trade with margin use 'margin-api'; When trade with super-margin use 'super-margin-api';When trade with c2c-margin use 'c2c-margin-api'
client-order-id string false NA Client order ID (maximum 64-character length)
self-match-prevent int false 0 self match prevent. 0: no, means allowing self-trading; 1: yes, means not allowing self-trading
stop-price string false NA Trigger price of stop limit order
operator}] string false NA Operation character of stop price, use 'gte' for greater than and equal (>=), use 'lte' for less than and equal (<=)

buy-limit-maker

If the order price is greater than or equal to the lowest selling price in the market, the order will be rejected.

If the order price is less than the lowest selling price in the market, the order will be accepted.

sell-limit-maker

If the order price is less than or equal to the highest buy price in the market, the order will be rejected.

If the order price is greater than the highest buy price in the market, the order will be accepted.

Response:

{
    "status": "ok",
    "data": [
        {
            "order-id": 361560582529749,
            "client-order-id": "2345"
        },
        {
            "client-order-id": "23456",
            "err-code": "order-value-min-error",
            "err-msg": "Order total cannot be lower than: 5 USDT"
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
order-id long The order id
client-order-id string The client order id (if available)
err-code string The error code (only for rejected order)
err-msg string The error message (only for rejected order)
</data>

If client order ID duplicates with a previous order , the endpoint responds that previous order's Id and client order ID.

Submit Cancel for an Order

API Key Permission：Trade
Rate Limit (NEW): 100times/2s

This endpoint submits a request to cancel an order.

HTTP Request

'order-id': the previously returned order id when order was created

Request Parameters

Parameter Data Type Required Default Description
order-id string true NA order id which needs to be filled in the path
symbol string false NA symbol which needs to be filled in the URL

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": "356501495694025"
}

Response Content

Error Code

Response:

{
    "status": "error",
    "err-code": "order-orderstate-error",
    "err-msg": "Incorrect order state",
    "data": null,
    "order-state": 7   // current order state
}

The possible values of "order-state" includes -

order-state Description
-1 order was already closed in the long past (order state = cancelled, partially-cancelled, filled, partially-filled)
1 created
3 submitted
4 partial-filled
5 partially-cancelled
6 filled
7 cancelled
10 cancelling

Submit Cancel for an Order (based on client order ID)

API Key Permission：Trade
Rate Limit (NEW): 100times/2s

This endpoint submit a request to cancel an order based on client-order-id .

HTTP Request

{
  "client-order-id": "a0001"
}

Request Parameters

Parameter Data Type Required Default Description
client-order-id string true NA Client order ID, it must exist within 8 hours, otherwise it is not allowed to use when placing a new order

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": 10
}

Response Content

Field Data Type Description
data int Cancellation status code
Status Code Description
-1 order was already closed in the long past (order state = cancelled, partially-cancelled, filled, partially-filled)
0 client-order-id not found
1 created
3 submitted
4 partial-filled
5 partially-cancelled
6 filled
7 cancelled
10 cancelling

Get All Open Orders

API Key Permission：Read
Rate Limit (NEW): 50times/2s

This endpoint returns all open orders which have not been filled completely.

HTTP Request

Request:

{
   "account-id": "100009",
   "symbol": "ethusdt",
   "side": "buy"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
account-id string false NA The account id used for this trade Refer to GET /v1/account/accounts
symbol string false NA The trading symbol to trade Refer to GET /v1/common/symbols
side string false NA Filter on the direction of the trade buy, sell
from string false NA start order ID the searching to begin with
direct string false (if field "from" is defined, this field "direct" becomes Required) NA searching direction prev - in ascending order from the start order ID; next - in descending order from the start order ID
size int false 100 The number of orders to return [1, 500]

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "symbol": "apnusdt",
            "source": "web",
            "price": "1.555550000000000000",
            "created-at": 1630633835224,
            "amount": "572.330000000000000000",
            "account-id": 13496526,
            "filled-cash-amount": "0.0",
            "client-order-id": "",
            "filled-amount": "0.0",
            "filled-fees": "0.0",
            "id": 357630527817871,
            "state": "submitted",
            "type": "sell-limit"
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
id long Order id
client-order-id string Client order id, can be returned from all open orders (if specified).
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
price string The limit price of limit order
created-at long The timestamp in milliseconds when the order was created
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-cash-amount string The filled total in quote currency
filled-fees string Transaction fee (Accurate fees refer to matchresults endpoint)
source string The source where the order was triggered, possible values: sys, web, api, app
state string Order status, valid values: created, submitted, partial-filled
stop-price string false
operator string false
</data>

Submit Cancel for Multiple Orders by Criteria

API Key Permission：Trade
Rate Limit (NEW): 50times/2s

This endpoint submit cancellation for multiple orders (not exceeding 100 orders per request) at once with given criteria.

This endpoint only submit the cancellation request, the actual cancellation result will need to be confirmed by other endpoints like order status, matchresult, etc.

HTTP Request

Request

{
  "account-id": "100009",
  "symbol": "btcusdt,btchusd",
  "side": "buy",
  "size": 5
}
Parameter Data Type Required Default Description Value Range
account-id string false NA The account id used for this cancel Refer to GET /v1/account/accounts
symbol string false all The trading symbol list (maximum 10 symbols, separated by comma, default value all symbols) All supported trading symbol, e.g. btcusdt, bccbtc.Refer to GET /v1/common/symbols
types string false NA One or more types of order to include in the search, use comma to separate. buy-market, sell-market, buy-limit, sell-limit, buy-ioc, sell-ioc, buy-stop-limit, sell-stop-limit, buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok
side string false NA Filter on the direction of the trade buy, sell
size int false 100 The number of orders to cancel [1, 100]

The above command returns JSON structured like this:

{
    "status":"ok",
    "data":{
        "success-count":2,
        "failed-count":0,
        "next-id":5454600
    }
}

Response Content

Field Data Type Description
status string status
<data> object
success-count integer The number of cancel request sent successfully
failed-count integer The number of cancel request failed
next-id integer the next order id that can be cancelled, -1 indicates no open orders
</data>

Submit Cancel for Multiple Orders by IDs

API Key Permission：Trade
Rate Limit (NEW): 50times/2s

This endpoint submit cancellation for multiple orders at once with given ids. It is suggested to use order-ids instead of client-order-ids, so that the cancellation is faster, more accurate and more stable.

HTTP Request

{
    "client-order-ids": [
         "12345", "123456"
    ]
}

Request Parameters

Parameter Data Type Required Description Value Range
order-ids string[] false The order ids to cancel (Either order-ids or client-order-ids can be filled in one batch request). It is suggest to use order-ids rather than client-order-ids, the former is faster and more stable No more than 50 orders per request
client-order-ids string[] false The client order ids to cancel (Either order-ids or client-order-ids can be filled in one batch request), it must exist already, otherwise it is not allowed to use when placing a new order No more than 50 orders per request

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": {
        "success": [
            "12345"
        ],
        "failed": [
            {
                "err-msg": "Incorrect order state",
                "order-state": 7,
                "order-id": "357631450723117",
                "err-code": "order-orderstate-error",
                "client-order-id": "123456"
            }
        ]
    }
}

Response Content

Field Data Type Description
status string 状态
<data> object
success array Cancelled order list (Can be order ID list or client order list, based on the request)
<failed> object Failed order list (Can be order ID list or client order list, based on the request)
order-id string The order id (if the request is based on order-ids)
client-order-id string The client order id (if the request is based on client-order-ids)
err-code string The error code (only applicable for rejected order)
err-msg string The error message (only applicable for rejected order)
order-state string Current order state (if available)
</failed>
</data>

The possible values of "order-state" includes -

order-state Description
-1 order was already closed in the long past (order state = canceled, partial-canceled, filled, partial-filled)
1 created
3 submitted
4 partial-filled
5 partial-canceled
6 filled
7 canceled
10 cancelling

Dead man’s switch

API Key Permission：Trade

The Dead man’s switch protects the user’s assets when the connection to the exchange is lost due to network or system errors.
Turn on/off the Dead man’s switch. If the Dead man’s switch is turned on and the API call isn’t sent twice within the set time, the platform will cancel all of your orders on the spot market（a maximum cancellation of 500 orders）.

HTTP Request

Request:

{
  "timeout": "10"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
timeout true int time out duration (unit：second); see notes for details NA 0 or >=5 seconds

Turn On Successful Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "currentTime": 1630491627230,
        "triggerTime": 1630491637230
    }
}

Turn Off Successful Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "currentTime": 1630491780445,
        "triggerTime": 0
    }
}

Turn On/Off Failed Response:

{
    "code": 2002,
    "message": "Invalid constraints error timeout",
    "data": null
}

Response Content

Name Required Type Description
code true int status code
message false string error description (if any)
<data> true object
currentTime true long current time
triggerTime true long trigger time
</data>

Get the Order Detail of an Order

API Key Permission：Read
Rate Limit (NEW): 50times/2s

This endpoint returns the detail of a specific order. If an order is created via API, then it's no longer queryable after being cancelled for 2 hours.

HTTP Request

Request Parameters

Name Required Type Description
order-id true string order id when order was created. Place it within path

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": {
        "id": 357632718898331,
        "symbol": "adausdt",
        "account-id": 13496526,
        "client-order-id": "23456",
        "amount": "5.000000000000000000",
        "price": "1.000000000000000000",
        "created-at": 1630649406687,
        "type": "buy-limit-maker",
        "field-amount": "0.0",
        "field-cash-amount": "0.0",
        "field-fees": "0.0",
        "finished-at": 0,
        "source": "spot-api",
        "state": "submitted",
        "canceled-at": 0
    }
}

Response Content

Field Data Type Description
status string status
<data> object
id integer order id
client-order-id string Client order id ("client-order-id" (if specified) can be returned from all open orders. "client-order-id" (if specified) can be returned only from closed orders (state <> canceled) created within 7 days. "client-order-id" (if specified) can be returned only from closed orders (state = canceled) created within 8 hours.)
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
account-id string The account id which this order belongs to
amount string The amount of base currency in this order
price string The limit price of limit order
created-at int The timestamp in milliseconds when the order was created
finished-at int The timestamp in milliseconds when the order was changed to a final state. This is not the time the order is matched.
canceled-at int The timestamp in milliseconds when the order was canceled, if not canceled then has value of 0
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-cash-amount string The filled total in quote currency
filled-fees string Transaction fee (Accurate fees refer to matchresults endpoint)
source string All possible order source (refer to introduction in this section)
state string All possible order state (refer to introduction in this section)
stop-price string trigger price of stop limit order
operator string operation character of stop price: gte, lte
</data>

Get the Order Detail of an Order (based on client order ID)

API Key Permission：Read
Rate Limit (NEW):50times/2s

This endpoint returns the detail of one order by specified client order id (within 8 hours). The order created via API will no longer be queryable after being cancelled for more than 2 hours. It is suggested to cancel orders via GET /v1/order/orders/{order-id}, which is faster and more stable.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description
clientOrderId string true NA Client order ID

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": {
        "id": 357632718898331,
        "symbol": "adausdt",
        "account-id": 13496526,
        "client-order-id": "23456",
        "amount": "5.000000000000000000",
        "price": "1.000000000000000000",
        "created-at": 1630649406687,
        "type": "buy-limit-maker",
        "field-amount": "0.0",
        "field-cash-amount": "0.0",
        "field-fees": "0.0",
        "finished-at": 0,
        "source": "spot-api",
        "state": "submitted",
        "canceled-at": 0
    }
}

Response Content

Field Data Type Description
status string status
<data> object
id integer order id
client-order-id string Client order id (only those orders created within 8 hours can be returned.)
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
account-id string The account id which this order belongs to
amount string The amount of base currency in this order
price string The limit price of limit order
created-at int The timestamp in milliseconds when the order was created
finished-at int The timestamp in milliseconds when the order was changed to a final state. This is not the time the order is matched.
canceled-at int The timestamp in milliseconds when the order was canceled, if not canceled then has value of 0
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-cash-amount string The filled total in quote currency
filled-fees string Transaction fee (Accurate fees refer to matchresults endpoint)
source string All possible order source (refer to introduction in this section)
state string All possible order state (refer to introduction in this section)
stop-price string trigger price of stop limit order
operator string operation character of stop price
</data>

If the client order ID is not found, following error message will be returned:

{
    "status": "error",
    "err-code": "base-record-invalid",
    "err-msg": "record invalid",
    "data": null
}

Get the Match Result of an Order

API Key Permission：Read
Rate Limit (NEW): 50times/2s

This endpoint returns the match result of an order.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description
order-id string true NA Order ID, place it into path

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "symbol": "polyusdt",
            "fee-currency": "poly",
            "source": "spot-web",
            "order-id": 345487249132375,
            "price": "0.338",
            "created-at": 1629443051839,
            "role": "taker",
            "match-id": 5014,
            "filled-amount": "147.928994082840236",
            "filled-fees": "0",
            "filled-points": "0.1",
            "fee-deduct-currency": "hbpoint",
            "fee-deduct-state": "done",
            "trade-id": 1085,
            "id": 313288753120940,
            "type": "buy-market"
        }
    ]
}

Response Content

Parameter Data Type Description
status string status
<data> object
id long Internal id
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
order-id long The order id of this order
match-id long The match id of this match
trade-id integer Unique trade ID (NEW)
price string The limit price of limit order
created-at int The timestamp in milliseconds when this record is created (slightly later than trade time)
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-fees string Transaction fee (positive value). If maker rebate applicable, revert maker rebate value per trade (negative value).
fee-currency string Currency of transaction fee or transaction fee rebate (transaction fee of buy order is based on base currency, transaction fee of sell order is based on quote currency; transaction fee rebate of buy order is based on quote currency, transaction fee rebate of sell order is based on base currency)
source string All possible order source (refer to introduction in this section)
role string the role in the transaction: taker or maker
filled-points string deduction amount (unit: in ht or hbpoint)
fee-deduct-currency string deduction type. if blank, the transaction fee is based on original currency; if showing value as "ht", the transaction fee is deducted by HT; if showing value as "hbpoint", the transaction fee is deducted by HB point.
fee-deduct-state string Fee deduction status，In deduction：ongoing，Deduction completed：done
</data>

Notes:

Search Past Orders

API Key Permission：Read
Rate Limit (NEW): 50times/2s

This endpoint returns orders based on a specific searching criteria. The order created via API will no longer be queryable after being cancelled for more than 2 hours.

HTTP Request

Request:


{
   "account-id": "100009",
   "amount": "10.1",
   "price": "100.1",
   "source": "api",
   "symbol": "ethusdt",
   "type": "buy-limit"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
symbol string true NA The trading symbol All supported trading symbols, e.g. btcusdt, bccbtc
types string false NA One or more types of order to include in the search, use comma to separate. buy-market, sell-market, buy-limit, sell-limit, buy-ioc, sell-ioc, buy-stop-limit, sell-stop-limit, buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok
start-time long false -48h Search starts time, UTC time in millisecond Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 180 days, query window shift should be within past 2 hours for cancelled order (state = "canceled")
end-time long false present Search ends time, UTC time in millisecond Value range [(present-179d), present], maximum query window size is 48 hours, query window shift should be within past 180 days, queriable range should be within past 2 hours for cancelled order (state = "canceled")
states string true NA One or more states of order to include in the search, use comma to separate. filled, partial-canceled, canceled
from string false NA Search order id to begin with NA
direct string false both Search direction when 'from' is used next, prev
size integer false 100 The number of orders to return [1-100]

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "id": 345487249132375,
            "symbol": "polyusdt",
            "account-id": 13496526,
            "client-order-id": "",
            "amount": "50.000000000000000000",
            "price": "0.0",
            "created-at": 1629443051822,
            "type": "buy-market",
            "field-amount": "147.928994082840236000",
            "field-cash-amount": "49.999999999999999768",
            "field-fees": "0.295857988165680472",
            "finished-at": 1629443051838,
            "source": "spot-web",
            "state": "filled",
            "canceled-at": 0
        }
    ]
}

Response Content

Field Data Type Description
status true string
<data> true object
id long Order id
client-order-id string Client order id ("client-order-id" (if specified) can be returned from all open orders. "client-order-id" (if specified) can be returned only from closed orders (state <> canceled) created within 7 days. only those closed orders (state = canceled) created within 8 hours can be returned.)
account-id long Account id
user-id integer User id
amount string The amount of base currency in this order
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
price string The limit price of limit order
created-at long The timestamp in milliseconds when the order was created
canceled-at long The timestamp in milliseconds when the order was canceled, or 0 if not canceled
finished-at long The timestamp in milliseconds when the order was finished, or 0 if not finished
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-cash-amount string The filled total in quote currency
filled-fees string Transaction fee (Accurate fees refer to matchresults endpoint)
source string All possible order source (refer to introduction in this section)
state string filled, partial-canceled, canceled
exchange string Internal data
batch string Internal data
stop-price string trigger price of stop limit order
operator string operation character of stop price
</data>

Error code for invalid start-time/end-time

err-code scenarios
invalid_interval Start time is later than end time; the time between start time and end time is greater than 2 days
invalid_start_time Start time is a future time; or start time is earlier than 180 days ago.
invalid_end_time end time is a future time; or end time is earlier than 180 days ago.

Search Historical Orders within 48 Hours

API Key Permission：Read
Rate Limit (NEW): 20times/2s

This endpoint returns orders based on a specific searching criteria. The orders created via API will no longer be queryable after being cancelled for more than 2 hours.

HTTP Request

Request: json { "symbol": "btcusdt", "start-time": "1556417645419", "end-time": "1556533539282", "direct": "prev", "size": "10" }

Request Parameters

Parameter Required Data Type Description Default Value Value Range
symbol false string The trading symbol to trade All supported trading symbol, e.g. btcusdt, bccbtc.Refer to GET /v1/common/symbols
start-time false long Start time (included) The time 48 hours ago UTC time in millisecond
end-time false long End time (included) The query time UTC time in millisecond
direct false string Direction of the query. (Note: If the total number of items in the search result is within the limitation defined in "size", this field does not take effect.) next prev, next
size false int Number of items in each response 100 [10-1000]

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "id": 357632718898331,
            "symbol": "adausdt",
            "account-id": 13496526,
            "client-order-id": "23456",
            "amount": "5.000000000000000000",
            "price": "1.000000000000000000",
            "created-at": 1630649406687,
            "type": "buy-limit-maker",
            "field-amount": "0.0",
            "field-cash-amount": "0.0",
            "field-fees": "0.0",
            "finished-at": 0,
            "source": "spot-api",
            "state": "submitted",
            "canceled-at": 0
        },
        {
            "id": 357632718898330,
            "symbol": "adausdt",
            "account-id": 13496526,
            "client-order-id": "2345",
            "amount": "5.000000000000000000",
            "price": "1.000000000000000000",
            "created-at": 1630649406687,
            "type": "buy-limit-maker",
            "field-amount": "0.0",
            "field-cash-amount": "0.0",
            "field-fees": "0.0",
            "finished-at": 0,
            "source": "spot-api",
            "state": "submitted",
            "canceled-at": 0
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
{account-id long Account ID
amount string Order size
canceled-at long Order cancellation time
created-at long Order creation time
field-amount string Executed order amount
field-cash-amount string Executed cash amount
field-fees string Transaction fee (Accurate fees refer to matchresults endpoint)
finished-at long Last trade time
id long Order ID
client-order-id string Client order id ("client-order-id" (if specified) can be returned only from closed orders (state <> canceled) created within 48 hours, upon order creation time. only those closed orders (state = canceled) created within 8 hours can be returned.)
price string Order price
source string All possible order source (refer to introduction in this section)
state string Order status ( filled, partial-canceled, canceled )
symbol string Trading symbol
stop-price string trigger price of stop limit order
operator string operation character of stop price. e.g. get, lte
type string All possible order type (refer to introduction in this section)
</data>
next-time long Next query "start-time" (in response of "direct" = prev), Next query "end-time" (in response of "direct" = next). Note: Only when the total number of items in the search result exceeded the limitation defined in "size", this field exists. UTC time in millisecond.

Search Match Results

API Key Permission：Read
Rate Limit (NEW): 20times/2s

This endpoint returns the match results of past and current filled, or partially filled orders based on specific search criteria.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description Value Range
symbol string true N/A The trading symbol to trade All supported trading symbol, e.g. btcusdt, bccbtc.Refer to GET /v1/common/symbols
types string false all The types of order to include in the search buy-market, sell-market, buy-limit, sell-limit, buy-ioc, sell-ioc, buy-limit-maker, sell-limit-maker, buy-stop-limit, sell-stop-limit
start-time false long Far point of time of the query window (unix time in millisecond). Searching based on transact-time. The maximum size of the query window is 48 hour. The query window can be shifted within 120 days. ((end-time) – 48hour) [((end-time) – 48hour), (end-time)]
end-time false long Near point of time of the query window (unix time in millisecond). Searching based on transact-time. The maximum size of the query window is 48 hour. The query window can be shifted within 120 days. current-time [(current-time) – 120days,(current-time)]
from string false N/A Search internal id to begin with if search next page, then this should be the last id (not trade-id) of last page; if search previous page, then this should be the first id (not trade-id) of last page
direct string false next Search direction when 'from' is used next, prev
size int false 100 The number of orders to return [1-500]

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "symbol": "polyusdt",
            "fee-currency": "poly",
            "source": "spot-web",
            "price": "0.338",
            "created-at": 1629443051839,
            "role": "taker",
            "order-id": 345487249132375,
            "match-id": 5014,
            "trade-id": 1085,
            "filled-amount": "147.928994082840236",
            "filled-fees": "0",
            "filled-points": "0.1",
            "fee-deduct-currency": "hbpoint",
            "fee-deduct-state": "done",
            "id": 313288753120940,
            "type": "buy-market"
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
id long Record id, non sequential, it can be used in "from" field for next request
symbol string The trading symbol to trade, e.g. btcusdt, bccbtc
order-id long The order id of this order
match-id long The match id of this match
trade-id long Unique trade ID
price string The limit price of limit order
created-at long The timestamp in milliseconds when this record is created
type string All possible order type (refer to introduction in this section)
filled-amount string The amount which has been filled
filled-fees string Transaction fee (positive value). If maker rebate applicable, revert maker rebate value per trade (negative value).
fee-currency string Currency of transaction fee or transaction fee rebate (transaction fee of buy order is based on base currency, transaction fee of sell order is based on quote currency; transaction fee rebate of buy order is based on quote currency, transaction fee rebate of sell order is based on base currency)
source string All possible order source (refer to introduction in this section)
role string The role in the transaction: taker or maker.
filled-points string deduction amount (unit: in ht or hbpoint)
fee-deduct-currency string deduction type: ht or hbpoint.
fee-deduct-state string Fee deduction status，In deduction：ongoing，Deduction completed：done
</data>

Notes:

Error code for invalid start-time/end-time

err-code scenarios
invalid_interval Start time is later than end time; the time between start time and end time is greater than 2 days
invalid_start_time Start time is a future time; or start time is earlier than 120 days ago.
invalid_end_time end time is a future time; or end time is earlier than 120 days ago.

Get Current Fee Rate Applied to The User

This endpoint returns the current transaction fee rate applied to the user.

API Key Permission：Read

HTTP Request

GET /v2/reference/transact-fee-rate

Request Parameters

Parameter Data Type Required Default Description Value Range
symbols string true NA The trading symbols to query, separated by comma Refer to GET /v1/common/symbols

Response:

{
    "code": 200,
    "data": [
        {
            "symbol": "btcusdt",
            "actualMakerRate": "0.002",
            "actualTakerRate": "0.002",
            "takerFeeRate": "0.002",
            "makerFeeRate": "0.002"
        },
        {
            "symbol": "apnusdt",
            "actualMakerRate": "0.002",
            "actualTakerRate": "0.002",
            "takerFeeRate": "0.002",
            "makerFeeRate": "0.002"
        },
        {
            "symbol": "htusdt",
            "actualMakerRate": "0.002",
            "actualTakerRate": "0.002",
            "takerFeeRate": "0.002",
            "makerFeeRate": "0.002"
        }
    ],
    "success": true
}

Response Content

Field Name Data Type Description
code integer Status code
message string Error message (if any)
<data> object
symbol string Trading symbol
makerFeeRate string Basic fee rate – passive side (positive value);If maker rebate applicable, revert maker rebate rate (negative value).
takerFeeRate string Basic fee rate – aggressive side
actualMakerRate string Deducted fee rate – passive side (positive value). If deduction is inapplicable or disabled, return basic fee rate.If maker rebate applicable, revert maker rebate rate (negative value).
actualTakerRate string Deducted fee rate – aggressive side. If deduction is inapplicable or disabled, return basic fee rate.
</data>

Note： - If makerFeeRate/actualMakerRate is positive，this field means the transaction fee rate. - If makerFeeRate/actualMakerRate is negative, this field means the rebate fee rate.

Error Code

Below is the error code and description returned by Trading APIs

Error Code Description
forbidden-trade-for-open-protect The current protection phase is open. You can place orders after the protection period ends (GMT+8)
base-argument-unsupported The specified parameter is not supported
base-system-error System internel error. For placing or canceling order, it is mostly due to cache issue, please try again later.
login-required Signature is missing, or user not find (key and uid not match).
parameter-required Stop-price or operator parameter is missing for stop-order type
base-record-invalid Failed to get data, please try again later
order-amount-over-limit The amount of order exceeds the limitation
base-symbol-trade-disabled The symbol is disabled for trading
base-operation-forbidden The operation is forbidden for current user or the symbol is not allowed to trade over OTC
account-get-accounts-inexistent-error The account doesn't exist in current user
account-account-id-inexistent The account id doesn't exist
sub-user-auth-required Isolated margin account is not enabled for sub user
order-disabled The symbol is pending and not allowed to place order
cancel-disabled The symbol is pending and not allowed to cancel order
order-invalid-price The order price is invalid, usually exceeds the 10% of latest trade price
order-accountbalance-error The account balance is insufficient
order-limitorder-price-min-error Sell price cannot be lower than specific price(limit price to sell cannot be lower than 90% of the market price)
order-limitorder-price-max-error Buy price cannot be higher than specific price(limit price to buy cannot be higher than 110% of the market price)
order-limitorder-amount-min-error Limit order amount can not be less than specific number
order-limitorder-amount-max-error Limit order amount can not be more than specific number
order-etp-nav-price-min-error Order price cannot be lower than specific percentage
order-etp-nav-price-max-error Order price cannot be higher than specific percentage
order-orderprice-precision-error Order price precision error
order-orderamount-precision-error Order amount precision error
order-value-min-error Order value cannot be lower than specific value
order-marketorder-amount-min-error Market order sell amount cannot be less than specific amount
order-marketorder-amount-buy-max-error Market order buy amount(value) cannot be more than specific amount(value)
order-marketorder-amount-sell-max-error Market order sell amount cannot be more than specific amount
order-holding-limit-failed Exceed the holding limit of the currency
order-type-invalid Order type is invalid
order-orderstate-error Order state is invalid
order-date-limit-error Order query date exceed the limit
order-source-invalid Order source is invalid
order-update-error Order update error
order-fl-cancellation-is-disallowed Liquidation order cannot be canceled
operation-forbidden-for-fl-account-state The operation is forbidden when the account is in liquidation
operation-forbidden-for-lock-account-state The operation is forbidden when the account is locked
fl-order-already-existed An unfilled liquidation order already exists
order-user-cancel-forbidden IOC or FOK order is not allowed to cancel
account-state-invalid Invalid status of liquidation account
order-price-greater-than-limit Order price is higher than the limitation before market opens
order-price-less-than-limit Order price is lower than the limitation before market opens
order-stop-order-hit-trigger The stop orders triggered immediately are not allowed
market-orders-not-support-during-limit-price-trading Market orders are not supported during limit-price trading
price-exceeds-the-protective-price-during-limit-price-trading The price exceeds the protective price during limit-price trading
invalid-client-order-id The parameter client order id is duplicated (within last 24h) in place or cancel order request
invalid-interval Query window is zero, negative or greater than limitation
invalid-start-date The start date is invalid
invalid-end-date The end date is invalid
invalid-start-time The start time is invalid
invalid-end-time The end time is invalid
validation-constraints-required The specified parameters is missing
symbol-not-support The symbol is not support for cross margin or C2C
not-found The order id is not found
base-not-found The record is not found

FAQ

Q1：What is client-order-id?

A： The client-order-id is an optional request parameter while placing order. It's string type which maximum length is 64. The client order id is generated by client, and is only valid within 8 hours (It’s only valid within 2 hours for the final state).

Q2：How to get the order size, price and decimal precision?

A： You can call API GET /v1/common/symbols to get the currency pair information, pay attention to the difference between the minimum amount and the minimum price.

Below are common errors:

Q3：Why I got insufficient balance error while placing an order just after a successful order matching?

A：To ensure the low latency of order update, Order update push is made directly after order matching. Meanwhile, the clearing service of that order may be still in progress at backend. It is suggested to follow either of below to ensure a successful order submission:

1、Subscribe to WebSocket topic accounts for getting account balance moves to ensure the completion of asset clearing.

2、After receiving WebSocket push message, check account balance from REST endpoint to ensure sufficient available balance for the next order submission.

3、Leave sufficient balance in your account.

Q4: What is the difference between 'filled-fees' and 'filled-points' in match result?

A: Transaction fee can be paid from either of below. They won't exist at the same time.

1、filled-fees: Filled-fee is also called transaction fee. It's charged from your income currency from the transaction. For example, if your purchase order of BTC/USDT got matched，the transaction fee will be based on BTC.

2、filled-points: If user enabled transaction fee deduction, the fee should be charged from either HT or Point. When there's sufficient fund in HT/Point, filled-fees is empty while filled-points has value. That means the deduction is made via HT/Point. User could refer to field fee-deduct-currency to get the exact deduction type of the transaction.

Q5: What is the difference between 'match-id' and 'trade-id' in matching result?

A: The match-id is the identity for order matching, while the trade-id is the unique identifier for each trade. One match-id may be correlated with multiple trade-id, or no trade-id(if the order is cancelled). For example, if a taker's order got matched with 3 maker's orders at the same time, it generates 3 trade IDs but only one match ID.

Q6: Why the order submission could be rejected even though the order price is set as same as current best bid (or best ask)?

A: For some extreme illiquid trading symbols, the best quote price at particular time might be far away from last trade price. But the price limit is actually based on last trade price which could possibly exclude best quote price from valid range for any new order. It is suggested to place orders based on the WebSocket pushed Bid and market data.

Q7: How to retrieve the trading symbols for margin trade

A: You can get details from Rest API GET /v1/common/symbols. The leverage-ratio represents the isolated-margin ratio. The super-margin-leverage-ratio represents the cross-margin.

The value 0 indicates that the trading symbols doesn't support margin trading.

Conditional Order

Introduction

By comparing with the existing stop limit order, the newly introduced conditional order does have following major differences:

1) Although the newly introduced conditional order is also triggered by stop price, before it being triggered, the Exchange will not lock order margin for this order. Only when this conditional order being successfully triggered, its order margin will be locked.
2) Conditional order does support not only limit order type but also market order type. (Trailing stop order only supports market order type.)
3) As advanced conditional order, trailing stop order does support additional triggering condition i.e. trailing rate. Only when latest market price breaks stop price, and continues to go up (or down), and then reverts back for a certain percentage which exceeding the pre-defined "trailing rate", this order can be triggered. The valid value range of trailing rate is between 0.1% and 5%.

Place a conditional order

API Key Permission: Trade
Rate Limit (NEW): 20times/2sec
Conditional order can be only placed via this endpoint instead of any endpoint in "Trading" section.

Request Parameter

Field Data Type Required Default Value Description Valid Value
accountId integer TRUE Account ID At present only support spot account id, margin account id, super-margin account. C2C margin account id is not supported at this point of time.
symbol string TRUE Trading symbol
orderPrice string FALSE Order price (invalid for market order)
orderSide string TRUE Order side buy,sell
orderSize string FALSE Order size (invalid for market buy order)
orderValue string FALSE Order value (only valid for market buy order)
timeInForce string FALSE gtc for orderType=limit; ioc for orderType=market Time in force gtc (invalid for orderType=market), boc (invalid for orderType=market), ioc, fok (invalid for orderType=market)
orderType string TRUE Order type limit,market
clientOrderId string TRUE Client order ID (max length 64-char)
stopPrice string TRUE Stop price
trailingRate string FALSE Trailing rate (only valid for trailing stop order) [0.001-0.050]

Note:
• The gap between orderPrice and stopPrice shouldn't exceed the price limit ratio. For example, a limit buy order's price couldn't be higher than 110% of market price, this limitation should be also applicable to orderPrice/stopPrice ratio.
• User has to make sure the clientOrderId's uniqueness. While the conditional order being triggered, if the clientOrderId is duplicated with another order (within 24hour) coming from same user, the conditional order will fail triggering.
• User has to make sure the corresponding account has sufficient fund for triggering this conditional order, otherwise it would cause conditional order triggering failure.
• timeInForce enum values: gtc - good till cancel，boc - book or cancel (also called as post only, or book only), ioc - immediate or cancel, fok - fill or kill

Response

{
    "code": 200,
    "data": {
        "clientOrderId": "a001"
    }
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE
clientOrderId string TRUE Client order ID
</data>

Cancel conditional orders (before triggering)

API Key Permission: Trade
Rate Limit (NEW): 20times/2sec
This endpoint only supports order cancellation for those conditional orders which have not triggered yet. To cancel a triggered order, please refer to the endpoints in "Trading" section.
Before a conditional order triggering, it can be only cancelled via this endpoint instead of any endpoint in "Trading" section.

Request

{
    "clientOrderIds": [
        "zy0002","zy0003"
    ]
}

Request Parameter

Field Data Type Required Default Value Description Valid Value
clientOrderIds string[] TRUE Client order ID (maximum 50 orders are allowed, Transfer in the form of as array)

Response

{
    "code": 200,
    "data": {
        "accepted": [
            "zy0002",
            "zy0003"
        ],
        "rejected": []
    }
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE
accepted string[] FALSE Accepted clientOrderId list
rejected string[] TRUE Rejected clientOrderId list
</data>

Query open conditional orders (before triggering)

API Key Permission: Read
Rate Limit (NEW): 20times/2sec
Search by orderOrigTime
This endpoint only returns those conditional orders which have not triggered with orderStatus value as created.
Before a conditional order triggering, it can be queried out through this endpoint instead of any endpoint in "Trading" section.

Request Parameter

Field Data Type Required Default Value Description Valid Value
accountId integer FALSE all Account ID
symbol string FALSE all Trading symbol
orderSide string FALSE all Order side buy,sell
orderType string FALSE all Order type limit,market
sort string FALSE desc Sorting order asc, desc
limit integer FALSE 100 Maximum number of items in one page [1,500]
fromId long FALSE First record ID in this query (only valid for next page querying)

Response

{
    "code": 200,
    "data": [
        {
            "lastActTime": 1630657250326,
            "orderOrigTime": 1630657250238,
            "symbol": "adausdt",
            "source": "api",
            "clientOrderId": "123",
            "orderSide": "buy",
            "orderType": "limit",
            "orderPrice": "0.1",
            "orderSize": "100",
            "accountId": 13496526,
            "timeInForce": "gtc",
            "stopPrice": "0.1",
            "orderStatus": "created"
        },
        {
            "lastActTime": 1630657243576,
            "orderOrigTime": 1630657243534,
            "symbol": "adausdt",
            "source": "api",
            "clientOrderId": "12",
            "orderSide": "buy",
            "orderType": "limit",
            "orderPrice": "0.1",
            "orderSize": "100",
            "accountId": 13496526,
            "timeInForce": "gtc",
            "stopPrice": "0.1",
            "orderStatus": "created"
        }
    ]
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE In ascening/descending order defined in 'sort'
accountId integer TRUE Account ID
source string TRUE Order source (api,web,ios,android,mac,windows,sys)
clientOrderId string TRUE Client order ID
symbol string TRUE Trading symbol
orderPrice string TRUE Order price (invalid for market order)
orderSize string FALSE Order size (invalid for market buy order)
orderValue string FALSE Order value (only valid for market buy order)
orderSide string TRUE Order side
timeInForce string TRUE Time in force
orderType string TRUE Order type
stopPrice string TRUE Stop price
trailingRate string FALSE Trailing rate (only valid for trailing stop order)
orderOrigTime long TRUE Order original time
lastActTime long TRUE Order last activity time
orderStatus string TRUE Order status (created)
</data>
nextId long FALSE First record ID in next page (only valid if exceeded page size)

Query conditional order history

API Key Permission: Read
Rate Limit (NEW): 20times/2sec
Search by orderOrigTime
This endpoint only returns those conditional orders which have been cancelled before triggering (orderStatus=canceled), or which have failed to trigger (orderStatus=rejected), or which have successfully triggered (orderStatus=triggered).
To further query the latest status of a successfully triggered conditonal order, please refer to the endpoints in "Trading" section.
The cancelled conditional order before triggering, as well as the conditional order failed to trigger, can be queried out through this endpoint instead of any endpoint in "Trading" section.

Request Parameter

Field Data Type Required Default Value Description Valid Value
accountId integer FALSE all Account ID
symbol string TRUE Trading symbol
orderSide string FALSE all Order side buy,sell
orderType string FALSE all Order type limit,market
orderStatus string TRUE Order status canceled,rejected,triggered
startTime long FALSE Farthest time
endTime long FALSE current time Nearest time
sort string FALSE desc Sorting order asc, desc
limit integer FALSE 100 Maximum number of items in one page [1-500]
fromId long FALSE First record ID in this query (only valid for next page querying)

Response

{
    "code": 200,
    "data": [
        {
            "orderOrigTime": 1630656758442,
            "lastActTime": 1630656880512,
            "symbol": "adausdt",
            "source": "api",
            "clientOrderId": "1234567",
            "orderSide": "buy",
            "orderType": "limit",
            "orderPrice": "0.1",
            "orderSize": "100",
            "accountId": 13496526,
            "timeInForce": "gtc",
            "stopPrice": "0.1",
            "orderStatus": "canceled"
        }
    ],
    "nextId": 9585084
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE In ascening/descending order defined in 'sort'
accountId integer TRUE Account ID
source string TRUE Order source
clientOrderId string TRUE Client order ID
orderId string FALSE Order ID (only valid for orderStatus=triggered)
symbol string TRUE Trading symbol
orderPrice string TRUE Order price (invalid for market order)
orderSize string FALSE Order size (invalid for market buy order)
orderValue string FALSE Order value (only valid for market buy order)
orderSide string TRUE Order side
timeInForce string TRUE Time in force
orderType string TRUE Order type
stopPrice string TRUE Stop price
trailingRate string FALSE Trailing rate (only valid for trailing stop order)
orderOrigTime long TRUE Order original time
lastActTime long TRUE Order last activity time
orderCreateTime long FALSE Order trigger time (only valid for orderStatus=triggered)
orderStatus string TRUE Order status (triggered,canceled,rejected)
errCode integer FALSE Status code in case of order triggering failure (only valid for orderStatus=rejected)
errMessage string FALSE Error message in case of order triggering failure (only valid for orderStatus=rejected)
</data>
nextId long FALSE First record ID in next page (only valid if exceeded page size)

Query a specific conditional order

API Key Permission: Read
Rate Limit (NEW): 20times/2sec
Search by orderOrigTime
To further query the latest status of a successfully triggered conditonal order, please refer to the endpoints in "Trading" section.
The conditional order before triggering, as well as the conditional order failed to trigger, can be queried out through this endpoint instead of any endpoint in "Trading" section.

Request Parameter

Field Data Type Required Default Value Description Valid Value
clientOrderId string TRUE Client order ID

Response

{
    "code": 200,
    "data": {
        "lastActTime": 1630656880512,
        "orderOrigTime": 1630656758442,
        "symbol": "adausdt",
        "source": "api",
        "orderStatus": "canceled",
        "clientOrderId": "1234567",
        "orderSide": "buy",
        "orderType": "limit",
        "orderPrice": "0.1",
        "orderSize": "100",
        "accountId": 13496526,
        "timeInForce": "gtc",
        "stopPrice": "0.1"
    }
}

Response Content

Field Data Type Required Description
code integer TRUE Status code
message string FALSE Error message (if any)
<data> object TRUE
accountId integer TRUE Account ID
source string TRUE Order source
clientOrderId string TRUE Client order ID
orderId string FALSE Order ID (only valid for orderStatus=triggered)
symbol string TRUE Trading symbol
orderPrice string TRUE Order price (invalid for market order)
orderSize string FALSE Order size (invalid for market buy order)
orderValue string FALSE Order value (only valid for market buy order)
orderSide string TRUE Order side
timeInForce string TRUE Time in force
orderType string TRUE Order type
stopPrice string TRUE Stop price
trailingRate string FALSE Trailing rate (only valid for trailing stop order)
orderOrigTime long TRUE Order original time
lastActTime long TRUE Order last activity time
orderCreateTime long FALSE Order trigger time (only valid for orderStatus=triggered)
orderStatus string TRUE Order status (created,triggered,canceled,rejected)
errCode integer FALSE Status code in case of order triggering failure (only valid for orderStatus=rejected)
errMessage string FALSE Error message in case of order triggering failure (only valid for orderStatus=rejected)
</data>

Error Code

Below is the error code and the description returned by Conditional Order APIs

Error Code Description
1001 Request URL is invalid
1002 Signature is missing or account id doesn't exist
1003 Signature is wrong
1006 Exceed rate limit
1007 Record is not found
2002 Specified parameter is missing or invalid
2003 Trading is disabled
3002 Order amount precision error
3003 Trigger price precision error
3004 Limit order amount is less than minimum amount
3005 Limit order amount is greater than maximum amount
3006 Limit order price is higher than maximum price
3007 Limit order price is lower than minimum price
3008 Order value is less than minimum value
3009 Market order amount is less than minimum amount
3010 Market order amount is greater than maximum amount
3100 Market orders can be accepted during limit price trading

Margin Loan (Cross/Isolated)

Introduction

Isolated/cross margin loan APIs provide loan related functionality such as requesting and repaying loan, loan querying and transfer.

Repay Margin Loan（Cross/Isolated ）

API Key Permission: Transaction

Frequency Limit: 2/s

Available Accounts: Main and Sub-Accounts

While repaying the loan, loan interest will be paid first if there is no appointed transactId. Otherwise, currency will not be authenticated.

HTTP Request

Request:

{
    "accountid": "1266826",
    "currency": "btc",
    "amount": "0.00800334",
    "transactId": "437"
}

Request Parameters

Field Data Type Mandotory Description
accountId string TRUE repayment account ID
currency string TRUE repayment currency
amount string TRUE repayment amount
transactId string FALSE loan transaction ID

Response:

{
  "code":200,
  "Data": [
      {
          "repayId":1174424,
          "repayTime":1600747722018
      }
   ]
}

Response Content

Field Data Type Mandotory Description
code integer TRUE status code
message string FALSE error description (if any)
<data> object TRUE
repayId string TRUE repayment ID
repayTime long TRUE repayment time (unix time in millisecond)
</data>

Note:

Transfer Asset from Spot Trading Account to Isolated Margin Account（Isolated）

API Key Permission：Trade
Rate Limit (NEW): 2times/2s

This endpoint transfers specific asset from spot trading account to isolated margin account.

HTTP Request

Requset

{
    "symbol": "ethusdt",
    "currency": "eth",
    "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
symbol string true NA The trading symbol, e.g. btcusdt, bccbtc
currency string true NA The currency to transfer
amount string true NA The amount of currency to transfer

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": 46971504,
    "code": 200
}

Response Content

Field Data Type Description
data integer Transfer id

Transfer Asset from Isolated Margin Account to Spot Trading Account（Isolated）

API Key Permission：Trade
Rate Limit (NEW): 2times/2s

This endpoint transfers specific asset from isolated margin account to spot trading account.

HTTP Request

{
    "symbol": "ethusdt",
    "currency": "eth",
    "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
symbol string true NA The trading symbol, e.g. btcusdt, bccbtc
currency string true NA The currency to transfer
amount string true NA The amount of currency to transfer

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": 46971504,
    "code": 200
}

Response Content

Field Data Type Description
data integer Transfer id

Get Loan Interest Rate and Quota（Isolated）

API Key Permission: Read
Rate Limit (NEW): 20times/2s

The endpoint returns loan interest rates and quota applied on the user.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description
symbols string false all Trading symbol (multiple pairs available, separated by comma)

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "btcusdt",
            "currencies": [
                {
                    "currency": "btc",
                    "interest-rate": "0.00098",
                    "min-loan-amt": "0.020000000000000000",
                    "max-loan-amt": "550.000000000000000000",
                    "loanable-amt": "0.045696000000000000",
                    "actual-rate": "0.00098"
                },
                {
                    "currency": "usdt",
                    "interest-rate": "0.00098",
                    "min-loan-amt": "100.000000000000000000",
                    "max-loan-amt": "4000000.000000000000000000",
                    "loanable-amt": "400.000000000000000000",
                    "actual-rate": "0.00098"
                }
            ]
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
symbol string Trading symbol
<currencies> object
currency string Currency
interest-rate string Basic daily interest rate
min-loan-amt string Minimal loanable amount
max-loan-amt string Maximum loanable amount
loanable-amt string Remaining loanable amount
actual-rate string Actual interest rate (if deduction is inapplicable or disabled, return basic daily interest rate)
</currencies>
</data>

Request a Margin Loan（Isolated）

API Key Permission：Trade
Rate Limit (NEW): 2times/2s

This endpoint places an order to apply a margin loan.

HTTP Request

Request:

{
  "symbol": "ethusdt",
  "currency": "eth",
  "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
symbol string true NA The trading symbol to borrow margin, e.g. btcusdt, bccbtc
currency string true NA The currency to borrow
amount string true NA The amount of currency to borrow (precision: 3 decimal places)

The above command returns JSON structured like this:

{
  "status": "ok",
  "data": 1000
}

Response Content

Field Data Type Description
status string Status
data integer Margin order id

Repay Margin Loan（Isolated）

API Key Permission：Trade
Rate Limit (NEW): 2times/2s

This endpoint repays margin loan with your asset in your margin account.

HTTP Request

'order-id': the previously returned order id when loan order was created

Request Parameters

Parameter Data Type Required Default Description
amount string true NA The amount of currency to repay
order-id string true NA Loan order ID (written in url path)

The above command returns JSON structured like this:

{  
  "data": 1000
}

Response Content

Field Data Type Description
data integer Margin order id

Search Past Margin Orders（Isolated）

API Key Permission：Read
Rate Limit (NEW): 100times/2s

This endpoint returns margin orders based on a specific searching criteria.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description Value Range
symbol string true NA The trading symbol to trade The trading symbol, e.g. btcusdt, bccbtc
states string false NA Order status list, multiple state allowed, separated by comma created, accrual (loaned), cleared (paid), invalid, failed
start-date string false -61d Search starts date, in format yyyy-mm-dd NA
end-date string false today Search ends date, in format yyyy-mm-dd NA
from string false NA Search order id to begin with NA
direct string false both Search direction when 'from' is used next, prev
size int false 100 The number of orders to return [1, 100]
sub-uid int false If not entered, by default it returns margin orders of current user Sub user ID (Required field while parent user querying sub user’s orders)

The above command returns JSON structured like this:

{
    "status": "ok",
    "data": [
        {
            "deduct-rate": "1",
            "created-at": 1595831651478,
            "updated-at": 1595832010845,
            "accrued-at": 1595831651478,
            "interest-amount": "0.004083000000000000",
            "loan-amount": "100.000000000000000000",
            "hour-interest-rate": "0.000040830000000000",
            "loan-balance": "0.000000000000000000",
            "interest-balance": "0.000000000000000000",
            "paid-coin": "0.004083000000000000",
            "day-interest-rate": "0.000980000000000000",
            "interest-rate": "0.000040830000000000",
            "user-id": 5574974,
            "account-id": 5463409,
            "currency": "usdt",
            "symbol": "btcusdt",
            "paid-point": "0.000000000000000000",
            "deduct-currency": "",
            "deduct-amount": "0",
            "id": 7839857,
            "state": "cleared"
        }
    ]
}

Response Content

Field Data Type Description
status string status
<data> object
id integer Order id
account-id integer Account id
user-id integer User id
symbol string The margin loan pair to trade, e.g. btcusdt, bccbtc
currency string The currency in the loan
created-at int The timestamp in milliseconds when the order was created
accrued-at int The timestamp in milliseconds when the last accure happened
loan-amount string The amount of the origin loan
loan-balance string The amount of the loan left
interest-rate string The loan interest rate
interest-amount string The accumulated loan interest
interest-balance string The amount of loan interest left
state string Loan state, possible values: created, accrual (loaned), cleared (paid), invalid, failed
paid-point string Paid Huobi Points for repayment
paid-coin string Paid original cryptocurrency for repayment
deduct-rate string Deduction rate for repayment
deduct-currency string Deduction currency for repayment
deduct-amount string Deduction value for repayment
updated-at long Update time
hour-interest-rate string Hourly interest rate
day-interest-rate string Daily interest rate
</data>

Get the Balance of the Margin Loan Account（Isolated）

API Key Permission：Read
Rate Limit (NEW): 100times/2s

This endpoint returns the balance of the margin loan account.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description
symbol string false NA The trading symbol, e.g. btcusdt.
If this is empty, then 'transfer-out-available' and 'loan-available' balance type won't be returned
sub-uid int false If not entered, by default it returns margin account details of current user Sub user ID (Required field while parent user querying sub user’s margin account details)

The above command returns JSON structured like this:

{  
  "data": [
    {
      "id": 18264,
      "type": "margin",
      "state": "working",
      "symbol": "btcusdt",
      "fl-price": "0",
      "fl-type": "safe",
      "risk-rate": "475.952571086994250554",
      "list": [
          {
              "currency": "btc",
              "type": "trade",
              "balance": "1168.533000000000000000"
          },
          {
              "currency": "btc",
              "type": "frozen",
              "balance": "0.000000000000000000"
          },
          {
              "currency": "btc",
              "type": "loan",
              "balance": "-2.433000000000000000"
          },
          {
              "currency": "btc",
              "type": "interest",
              "balance": "-0.000533000000000000"
          },
          {
              "currency": "btc",
              "type": "transfer-out-available",
              "balance": "1163.872174670000000000"
          },
          {
              "currency": "btc",
              "type": "loan-available",
              "balance": "8161.876538350676000000"
          }
      ]
    }
  ]
}

Response Content

Field Data Type Description
<data> true object
id true int
type true string
symbol string The margin loan pair, e.g. btcusdt, bccbtc
state string Loan state, possible values: created, accrual (loaned), cleared (paid), invalid
risk-rate string The risk rate
fl-price string The price which margin closeout was triggered
<list> array The list of margin accounts and their details
currency string The currency name
type string The sub account type, possible values: trade, frozen, loan, interest ,transfer-out-available, loan-available
balance string The negative balance means the loan or interest that need to repay. All trade balance can be transferred out if transfer-out-available balance is -1
</list>
</data>

Transfer Asset from Spot Trading Account to Cross Margin Account（Cross）

API Key Permission：Trade

This endpoint transfers specific asset from spot trading account to cross margin account.

HTTP Request

Request:

{
  "currency": "eth",
  "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
currency string true NA Currency
amount string true NA Transfer amount

The above command returns JSON structured like this:

{  
  "status": "ok",
  "data": 1000
}

Response Content

Field Data Type Description
data integer Transfer id

Transfer Asset from Cross Margin Account to Spot Trading Account（Cross）

API Key Permission：Trade

This endpoint transfers specific asset from cross margin account to spot trading account.

HTTP Request

Request:

{
  "currency": "eth",
  "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
currency string true NA Currency
amount string true NA Transfer amount

The above command returns JSON structured like this:

{  
  "status": "ok",
  "data": 1000
}

Response Content

Field Data Type Description
data integer Transfer id

Get Loan Interest Rate and Quota（Cross）

API Key Permission: Read

This endpoint returns loan interest rates and loan quota applied on the user.

HTTP Request

Request Parameters

Null

Response:

{
    "status": "ok",
    "data": [
        {
            "currency": "bch",
            "interest-rate": "0.00098",
            "min-loan-amt": "0.35",
            "max-loan-amt": "3500",
            "loanable-amt": "0.70405181",
            "actual-rate": "0.000343"
        },
        {
            "currency": "btc",
            "interest-rate": "0.00098",
            "min-loan-amt": "0.01",
            "max-loan-amt": "100",
            "loanable-amt": "0.02281914",
            "actual-rate": "0.000343"
        },
        {
            "currency": "eos",
            "interest-rate": "0.00098",
            "min-loan-amt": "30",
            "max-loan-amt": "300000",
            "loanable-amt": "57.69175296",
            "actual-rate": "0.000343"
        },
        {
            "currency": "eth",
            "interest-rate": "0.00098",
            "min-loan-amt": "0.5",
            "max-loan-amt": "6000",
            "loanable-amt": "1.06712197",
            "actual-rate": "0.000343"
        },
        {
            "currency": "ltc",
            "interest-rate": "0.00098",
            "min-loan-amt": "1.5",
            "max-loan-amt": "15000",
            "loanable-amt": "3.28947368",
            "actual-rate": "0.000343"
        },
        {
            "currency": "usdt",
            "interest-rate": "0.00098",
            "min-loan-amt": "100",
            "max-loan-amt": "1500000",
            "loanable-amt": "200.00000000",
            "actual-rate": "0.000343"
        },
        {
            "currency": "xrp",
            "interest-rate": "0.00098",
            "min-loan-amt": "380",
            "max-loan-amt": "4000000",
            "loanable-amt": "734.21439060",
            "actual-rate": "0.000343"
        }
    ],
    "code": 200
}

Response Content

Field Data Type Description
status string status
<data> object
currency string Currency
interest-rate string Basic daily interest rate
min-loan-amt string Minimal loanable amount
max-loan-amt string Maximum loanable amount
loanable-amt string Remaining loanable amount
actual-rate string Actual interest rate post deduction (if deduction is inapplicable or disabled, return basic daily interest rate)
</data>
code int status code

Request a Margin Loan（Cross）

API Key Permission：Trade

This endpoint places an order to apply for a margin loan.

HTTP Request

Request:

{
  "currency": "eth",
  "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
currency string true NA The currency to borrow
amount string true NA The amount of currency to borrow (precision: 3 decimal places)

The above command returns JSON structured like this:

{  
  "status": "ok",
  "data": 1000
}

Response Content

Field Data Type Description
status string status
data integer Margin order id

Repay Margin Loan（Cross）

API Key Permission：Trade

This endpoint repays margin loan with you asset in your margin account.

HTTP Request

'order-id': the previously returned order id when loan order was created

Request:

{
  "amount": "1.0"
}

Request Parameters

Parameter Data Type Required Default Description
order-id string true Loan order ID (written in url path)
amount string true NA The amount of currency to repay

The above command returns JSON structured like this:

{  
  "status": "ok",
  "data": null
}

Response Content

Field Data Type Description
status string status
data null NA

Search Past Margin Orders（Cross）

API Key Permission：Read

This endpoint returns margin orders based on a specific searching criteria.

HTTP Request

Request Parameters

Parameter Data Type Required Default Description Value Range
start-date string false -61d Search starts date, in format yyyy-mm-dd NA
end-date string false today Search ends date, in format yyyy-mm-dd NA
currency string false NA Currency NA
state string false all Order status created, accrual (loaned), cleared (paid), invalid
from string false 0 Search order id to begin with NA
direct string false next Search direction when 'from' is used next, prev
size string false 10 The number of orders to return [10-100]
sub-uid long false If not specified, returns loan order list of current logged in user Sub user UID

The above command returns JSON structured like this:

{
    "status":"ok",
    "data":[
        {
            "loan-balance":"0.100000000000000000",
            "interest-balance":"0.000200000000000000",
            "loan-amount":"0.100000000000000000",
            "accrued-at":1511169724531,
            "interest-amount":"0.000200000000000000",
            "filled-points":"0.2",
            "filled-ht":"0.2",
            "currency":"btc",
            "id":394,
            "state":"accrual",
            "account-id":17747,
            "user-id":119913,
            "created-at":1511169724531
        }
    ]
}

Response Content

Field Data Type Description
status true string
<data> true object
id integer Order id
account-id integer Account id
user-id integer User id
currency string The currency in the loan
filled-points string Point deduction amount
filled-ht string HT deduction amount
created-at int The timestamp in milliseconds when the order was created
accrued-at int The timestamp in milliseconds when the last accure happened
loan-amount string The amount of the origin loan
loan-balance string The amount of the loan left
interest-amount string The accumulated loan interest
interest-balance string The amount of loan interest left
state string Loan state, possible values: created, accrual (loaned), cleared (paid), invalid
</data>

Get the Balance of the Margin Loan Account（Cross）

API Key Permission：Read

This endpoint returns the balance of the margin loan account.

HTTP Request

Request Parameters

Field Name Mandotory Data Type Description Default Value Value Range
sub-uid false long Sub user UID If not specified, returns account balance of current logged in user

The above command returns JSON structured like this:

{
    "status":"ok",
    "data":{
        "id":18264,
        "type":"cross-margin",
        "state":"working",
        "risk-rate":"1000",
        "acct-balance-sum":"12312.123123",
        "debt-balance-sum":"1231.2123123",
        "list":[
            {
                "currency":"btc",
                "type":"trade",
                "balance":"1168.533000000000000000"
            },
            {
                "currency":"btc",
                "type":"frozen",
                "balance":"0.000000000000000000"
            },
            {
                "currency":"btc",
                "type":"loan",
                "balance":"-2.433000000000000000"
            },
            {
                "currency":"btc",
                "type":"interest",
                "balance":"-0.000533000000000000"
            },
            {
                "currency":"btc",
                "type":"transfer-out-available",  
                "balance":"1163.872174670000000000"
            },
            {
                "currency":"btc",
                "type":"loan-available",  
                "balance":"8161.876538350676000000"
            }
        ]
    }
}

Response Content

Field Data Type Description
status true string
<data> true object
id integer
type integer
state string account state: working, fl-sys, fl-end, fl-negative
risk-rate string
acct-balance-sum string
debt-balance-sum string
<list> array
currency string
type string account type: trade, frozen, loan, interest, transfer-out-available, loan-available
balance string The negative balance means the loan or interest that need to repay. All trade balance can be transferred out if transfer-out-available balance is -1
</list>
</data>

Repayment Record Reference

API Key Permission: Read

Frequency Limit: 2/s

Available Accounts: Main and Sub-Accounts

Sort by "repayTime"

HTTP Request

Request Parameters

Field Data Type Mandotory Description
repayId string FALSE repayment transaction ID
accountId string FALSE account ID (default value: all accounts)
currency string FALSE borrowing/lending currency (default value: all currencies)
startTime long FALSE start time (unix time in millisecond; range: [(endTime – x D), endTime]; default value: (endTime – x D)
endTime long FALSE end time (unix time in millisecond；range: [(present time – y D), present time]; default value: present time)
sort string FALSE sort direction (value: asc, desc; default value: desc)
limit integer FALSE max return items per page (range: [1-100]; default value: 50)
fromId long FALSE search ID from the start (only available when searching for the next page)

Response:

{
     "code":200,
     "data":[
         {
             "repayId": 1174413,
             "repayTime":1600747389111,
             "accountId": 1266826,
             "currency":"btc",
             "repaidAmount": "0.00200083",
             "transactIds": 
                  {
                      "transactId":502,
                      "repaidprincipal": "0.00199666",
                      "repaidInterest": "0.00000417",
                      "paidHt": "0",
                      "paidPoint": "0"
                  }
            }
     ]
}

Response Content

Field Data Type Mandotory Description
code integer TRUE status code
message string FALSE error description (if any)
<data> object TRUE sorted by the appointed order
repayId string TRUE repayment transaction ID
repayTime long TRUE repayment transaction time (unix time in millisecond)
accountId string TRUE repayment account ID
currency string TRUE repayment currency
repaidAmount string TRUE repaid amount
<transactIds> object TRUE ID list of original loan transactions (arranged by order of repaymen time)
transactId long TRUE original loan transaction ID
repaidPrincipal string TRUE principal repaid
repaidInterest string TRUE interest repaid
paidHt string TRUE HT paid
paidPoint string TRUE point paid
</transactIds>
</data>
nextId long FALSE search the start ID in the next page (return only when there is data in the next page)

Error Code

Below is the error code and description for Isolated margin loan APIs

Error Code Description
account-transfer-balance-insufficient-error Account balance is insufficient
account-transfer-balance-overflow-error Account balance is overflow
base-msg Customized error, check error message
base-system-error Server internal error
base-currency-error currency is invalid
base-symbol-error symbol is invalid
base-margin-symbol-invalid symbol is invalid for margin
base-record-invalid The data is not found
base-request-timeout Request timeout, try again later
base_request_exceed_number_limit Request exceeds number limit, try again later
base-date-limit-error Date is invalid
base-update-error Update operation error
base-operation-forbidden Operation is forbidden
dw-insufficient-balance Account balance is insufficient
dw-account-transfer-error Transfer error
frequent-invoke Operates too frequently, try again later
loan-order-not-found Loan order is not found
loan-amount-scale-limit Loan order amount precision error
loan-repay-max-limit Repay amount is greater than requested
loan-insufficient-balance Loan account balance is insufficient
login-required Signature is missing
margin-country-not-allow The registered country is forbidden to apply for margin
margin-country-auth-required Your IP is not allowed, require ID verification
margin-trading-is-not-available Isolated margin trading is not available
margin-account-state-error Margin account state is abnormal (liquidation)
risk-verification-failed Risk verification failed
sub-user-auth-required Sub user is not authorized

Below is the error code and description for Cross margin loan APIs (including general margin)

Error Code Description
abnormal-users-cannot-transfer Abnormal user cannot transfer
account-explosion-in-prohibited-transfer Account is explosion and transfer is prohibited
account-is-abnormal-retry-after-refresh Account is abnormal, try again later
account-balance-insufficient-error Account balance is insufficient
account-cannot-be-inquired Account is not found
base-not-in-white-list Operation is not allowed for current user
base-currency-error Currency is not found
base-operation-forbidden Operation is forbidden
base-user-request-exceed-limit Operates too frequently, try again later
base-currency-not-open The currency is not enabled
beyond-maximum-number-of-rollover Transfer amount exceed the limit
exceed-maximum-amount Exceed the limit
start-date-cannot-greater-than-end-date Start date cannot be greater than end date
frequent-invoke Operates too frequently
insufficient-exchange-fund Exchange fund is insufficient
loan-order-not-found Loan order is not found
loan-amount-scale-limit Loan order amount precision error
loan-repay-max-limit Repay amount is greater than requested
loan-insufficient-balance Loan account balance is insufficient
loan-fee-rate-compute-fail Loan fee is abnormal
login-required Signature is missing
margin-subuser-no-permission Sub user has no permission
normal-and-warehouse-can-transfer Normal and warehouse user can transfer
order-orderamount-precision-error Order amount precision error
require-exchange-id Exchange id is required
subacount-currency-not-exit Sub account for this currency does not exist
system-busy System is busy
unsupport-kyc-info KYC info is unsupported
uc-network-error Network error for User Center, try again later
uncreated-currency-cannot-be-drawn Uncreated sub account cannot be drawn

FAQ

Q1: I can see I have loanable amount in my margin account, why the API returns no sufficient amount error when I apply margin loan?

A: The available amount depends on not only account available amount, but also the system available amount. Due to risk control, the system has a max available amount everyday. If the total loan amount reaches the max value, user will fail to apply for loan, unless someone repays the loan in the same day. Right now we are implementing a more user-friendly solution that provides more accurate information to API users.

Websocket Market Data

Introduction

Websocket URL

Websocket Market Feed (excluding MBP incremental channel & its REQ channel)

wss://api.huobi.pro/ws or wss://api-aws.huobi.pro/ws

MBP incremental channel & its REQ channel)

wss://api.huobi.pro/feed or wss://api-aws.huobi.pro/feed

Data Format

All return data of websocket Market APIs are compressed with GZIP so they need to be unzipped.

Heartbeat and Connection

{"ping": 1492420473027}

After connected to Huobi's Websocket server, the server will send heartbeat periodically (currently at 5s interval). The heartbeat message will have an integer in it, e.g.

{"pong": 1492420473027}

When client receives this heartbeat message, it should respond with a matching "pong" message which has the same integer in it, e.g.

Subscribe to Topic

Sub request:

{
  "sub": "market.btcusdt.kline.1min",
  "id": "id1"
}

To receive data you have to send a "sub" message first.

{ "sub": "topic to sub", "id": "id generate by client" }

Sub response:

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.kline.1min",
  "ts": 1489474081631
}

After successfully subscribed, you will receive a response to confirm subscription

Then, you will received messages when there is any update in the subcribed topics.

Unsubscribe

UnSub request:

{
  "unsub": "market.btcusdt.trade.detail",
  "id": "id4"
}

To unsubscribe, you need to send below message

{ "unsub": "topic to unsub", "id": "id generate by client" }

UnSub response:

{
  "id": "id4",
  "status": "ok",
  "unsubbed": "market.btcusdt.trade.detail",
  "ts": 1494326028889
}

And you will receive a message to confirm the action.

Pull Data

While connected to websocket, you can also use it in pull style by sending message to the server.

To request pull style data, you send below message

{ "req": "topic to req", "id": "id generate by client" }

You will receive a response accordingly and immediately

Rate Limit

Rate limt of pull style query (req)

The limitation of single connection is 100 ms.

Market Candlestick

This topic sends a new candlestick whenever it is available.

Topic

market.$symbol$.kline.$period$

Subscribe request

{
  "sub": "market.ethbtc.kline.1min",
  "id": "id1"
}

Topic Parameter

Parameter Data Type Required Description Value Range
symbol string true Trading symbol All supported trading symbol, e.g. btcusdt, bccbtc. (to retrieve candlesticks for ETP NAV, symbol = ETP trading symbol + suffix 'nav'，for example: btc3lusdtnav)
period string true Candlestick interval 1min, 5min, 15min, 30min, 60min, 4hour, 1day, 1mon, 1week, 1year

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.ethbtc.kline.1min",
  "ts": 1489474081631 //system response time
}

Update example

{
    "ch":"market.ethbtc.kline.1min",
    "ts":1630981694370,
    "tick":{
        "id":1630981680,
        "open":0.074849,
        "close":0.074848,
        "low":0.074848,
        "high":0.074849,
        "amount":2.4448,
        "vol":0.1829884187,
        "count":3
    }
}

Update Content

Field Data Type Description
ch string Data belonged channel，Format：market.$symbol.kline.$period
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id integer UNIX epoch timestamp in second as response id
amount float Aggregated trading volume during the interval (in base currency)
count integer Number of trades during the interval
open float Opening price during the interval
close float Closing price during the interval
low float Low price during the interval
high float High price during the interval
vol float Aggregated trading value during the interval (in quote currency)
</tick>

Market Ticker

Retrieve the market ticker,data is pushed every 100ms.

Topic

market.$symbol.ticker

Subscribe request

{
  "sub": "market.btcusdt.ticker"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
symbol string true NA The trading symbol to query All supported trading symbol, e.g. btcusdt, bccbtc.Refer to /v1/common/symbols

The above command returns JSON structured like this:

{
    "ch":"market.btcusdt.ticker",
    "ts":1630982370526,
    "tick":{
        "open":51732,
        "high":52785.64,
        "low":51000,
        "close":52735.63,
        "amount":13259.24137056181,
        "vol":687640987.4125315,
        "count":448737,
        "bid":52732.88,
        "bidSize":0.036,
        "ask":52732.89,
        "askSize":0.583653,
        "lastPrice":52735.63,
        "lastSize":0.03
    }
}

Response Content

Field Data Type Description
ch string Data belonged channel，Format：market.$symbol.ticker
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id long The internal identity
amount float Accumulated trading volume of last 24 hours (rotating 24h), in base currency
count integer The number of completed trades (rotating 24h)
open float The opening price of last 24 hours (rotating 24h)
close float The last price of last 24 hours (rotating 24h)
low float The lowest price of last 24 hours (rotating 24h)
high float The highest price of last 24 hours (rotating 24h)
vol float Accumulated trading value of last 24 hours (rotating 24h), in quote currency
bid float Best bid price
bidSize float Best bid size
ask float Best ask price
askSize float Best ask size
lastPrice float Last traded price
lastSize float Last traded size
</tick>

Market Depth

This topic sends the latest market by price order book in snapshot mode at 1-second interval.

Topic

market.$symbol.depth.$type

Subscribe request

{
  "sub": "market.btcusdt.depth.step0",
  "id": "id1"
}

Topic Parameter

Parameter Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol Refer to GET /v1/common/symbols
type string true step0 Market depth aggregation level, details below step0, step1, step2, step3, step4, step5

"type" Details

Value Description
step0 No market depth aggregation
step1 Aggregation level = precision*10
step2 Aggregation level = precision*100
step3 Aggregation level = precision*1000
step4 Aggregation level = precision*10000
step5 Aggregation level = precision*100000

While type is set as ‘step0’, the market depth data supports up to 150 levels. While type is set as ‘step1’, ‘step2’, ‘step3’, ‘step4’, or ‘step5’, the market depth data supports up to 20 levels.

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.depth.step0",
  "ts": 1489474081631 //system response time
}

Update example

{
    "ch":"market.btcusdt.depth.step0",
    "ts":1630983549503,
    "tick":{
        "bids":[
            [
                52690.69,
                0.36281
            ],
            [
                52690.68,
                0.2
            ]
        ],
        "asks":[
            [
                52690.7,
                0.372591
            ],
            [
                52691.26,
                0.13
            ]
        ],
        "version":136998124622,
        "ts":1630983549500
    }
}

Update Content

Field Data Type Description
ch string Data belonged channel，Format：market.$symbol.depth.$type
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
bids object The current all bids in format [price, size]
asks object The current all asks in format [price, size]
version integer Internal data
ts integer The UNIX timestamp in milliseconds adjusted to Singapore time
</tick>

Pull Request

Pull request is supported.

{
  "req": "market.btcusdt.depth.step0",
  "id": "id10"
}

Market By Price (incremental update)

User could subscribe to this channel to receive incremental update of Market By Price order book. Refresh message, the full image of the order book, are acquirable from the same channel, upon "req" request.

MBP incremental channel & its REQ channel)

wss://api.huobi.pro/feed or wss://api-aws.huobi.pro/feed

Suggested downstream data processing:
1) Subscribe to incremental updates and start to cache them;
2) Request refresh message (with same number of levels), and base on its "seqNum" to align it with the cached incremental message which has the same "prevSeqNum";
3) Start to continuously process incremental messages to build up MBP book;
4) The "prevSeqNum" of the current incremental message must be the same with "seqNum" of the previous message, otherwise it implicates message loss which should require another round of refresh message retrieval and alignment;
5) Once received a new price level from incremental message, that price level should be inserted into appropriate position of existing MBP book;
6) Once received an updated "size" at the existing price level from incremental message, the size should be replaced directly by the new value;
7) Once received a "size=0" at existing price level from incremental message, that price level should be removed from MBP book;
8) If one incremental message includes updates of multiple price levels, all of those levels should be updated simultaneously in MBP book.

Currently Huobionly supports 5-level/20-level MBP incremental channel and 150-level/400-level incremental channel, the differences between them are -
1) Different depth of market.
2) 5-level/20-level incremental MBP is a tick by tick feed, which means whenever there is an order book change at that level, it pushes an update; 150-levels/400-level incremental MBP feed is based on the gap between two snapshots at 100ms interval.
3) While there is single side order book update, either bid or ask, the incremental message sent from 5-level/20-level MBP feed only contains that side update. 

{
    "ch":"market.btcusdt.mbp.5",
    "ts":1630985211662,
    "tick":{
        "seqNum":136999309829,
        "prevSeqNum":136999309815,
        "bids":[
            [
                52771.08,
                1.804671
            ]
        ]
    }
}

But the incremental message from 150-levels/400-level MBP feed contains not only that side update and also a blank object for another side.

{
    "ch":"market.btcusdt.mbp.150",
    "ts":1573199608679,
    "tick":{
        "seqNum":100020146795,
        "prevSeqNum":100020146794,
        "bids":[ ],
        "asks":[
            [645.14,26.75597395914065]
        ]
    }
}

In the near future, Huobiwill align the update behavior of 150-level//400-level incremental channel with 5-level/20-level, which means while single side order book changed (either bid or ask), the update message will be no longer including a blank object for another side.
4) While there is nothing change between two snapshots in past 100ms, the 150-levels/400-level incremental MBP feed still sends out a message which contains two blank objects – bids & asks. 

{
    "ch":"market.zecusdt.mbp.150",
    "ts":1585074391470,
    "tick":{
        "seqNum":100772868478,
        "prevSeqNum":100772868476,
        "bids":[  ],
        "asks":[  ]
    }
}

But 5-level/20-level incremental channel won’t disseminate any update in such a case.
In the future, Huobiwill align the update behavior of 150-level/400-level incremental channel with 5-level/20-level, which means while there is no order book change at all, the channel will be no longer disseminating messages of blank object any more.
5) 5-level/20-level incremental channel only supports the following symbols at this stage: btcusdt, ethusdt, xrpusdt, eosusdt, ltcusdt, etcusdt, adausdt, dashusdt, bsvusdt, htusdt, dotusdt, linkusdt, iotausdt, zecusdt, trxusdt, xmrusdt, arusdt, dfausdt, nftusdt, uniusdt, dogeusdt, solusdt, xecusdt, lunausdt, bchusdt, maticusdt, vetusdt, xlmusdt, filusdt, thetausdt. while 150-level/400-level incremental channel supports all symbols.

REQ channel supports refreshing message for 5-level, 20-level, and 150-level.

Subscribe incremntal updates

market.$symbol.mbp.$levels

Sub request

{
  "sub": "market.btcusdt.mbp.5",
  "id": "id1"
}

Request refresh update

market.$symbol.mbp.$levels

Req request

{
  "req": "market.btcusdt.mbp.5",
  "id": "id2"
}

Parameters

Field Name Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol (wildcard inacceptable)
levels integer true NA Number of price levels (Valid value: 5,20,150,400) Only support the number of price levels at 5, 20,150 or 400 at this point of time.

Response (Incremental update subscription)

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.mbp.5",
  "ts": 1489474081631 //system response time
}

Incremental Update (Incremental update subscription)

{
    "ch": "market.btcusdt.mbp.5",
    "ts": 1573199608679, //system update time
    "tick": {
            "seqNum": 100020146795,
            "prevSeqNum": 100020146794,
            "asks": [
                 [645.140000000000000000, 26.755973959140651643] // [price, size]
           ]
    }
}

Response (Refresh update acquisition)

{
    "id": "id2",
    "rep": "market.btcusdt.mbp.5",
    "status": "ok",
    "data": {
        "seqNum": 100020142010,
        "bids": [
            [618.37, 71.594], // [price, size]
            [423.33, 77.726],
            [223.18, 47.997],
            [219.34, 24.82],
            [210.34, 94.463]
    ],
        "asks": [
            [650.59, 14.909733438479636],
            [650.63, 97.996],
            [650.77, 97.465],
            [651.23, 83.973],
            [651.42, 34.465]
        ]
    }
}

Update Content

Field Name Data Type Description
seqNum integer Sequence number of the message
prevSeqNum integer Sequence number of previous message
bids object Bid side, (in descending order of "price"), ["price","size"]
asks object Ask side, (in ascending order of "price"), ["price","size"]

Market By Price (refresh update)

User could subscribe to this channel to receive refresh update of Market By Price order book. The update interval is around 100ms.

Subscription

market.$symbol.mbp.refresh.$levels

{
"sub": "market.btcusdt.mbp.refresh.20",
"id": "id1"
}

Parameters

Field Name Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol (wildcard inacceptable)
levels integer true NA Number of price levels 5,10,20

Response

{
"id": "id1",
"status": "ok",
"subbed": "market.btcusdt.mbp.refresh.20",
"ts": 1489474081631 //system response time
}

Response

{
"ch": "market.btcusdt.mbp.refresh.20",
"ts": 1573199608679, //system update time
"tick": {

        "seqNum": 100020142010,
        "bids": [
            [618.37, 71.594], // [price, size]
            [423.33, 77.726],
            [223.18, 47.997],
            [219.34, 24.82],
            [210.34, 94.463], ... // rest levels omitted
        ],
        "asks": [
            [650.59, 14.909733438479636],
            [650.63, 97.996],
            [650.77, 97.465],
            [651.23, 83.973],
            [651.42, 34.465], ... // rest levels omitted
        ]
}
}

Update Content

Field Name Data Type Description
seqNum integer Sequence number of the message
bids object Bid side, (in descending order of "price"), ["price","size"]
asks object Ask side, (in ascending order of "price"), ["price","size"]

Best Bid/Offer

User can receive BBO (Best Bid/Offer) update in tick by tick mode.

Topic

market.$symbol.bbo

Subscribe request

{
  "sub": "market.btcusdt.bbo",
  "id": "id1"
}

Topic parameter

Parameter Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol Refer to GET /v1/common/symbols

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.bbo",
  "ts": 1489474081631 //system response time
}

Update example

{
    "ch":"market.btcusdt.bbo",
    "ts":1630994555540,
    "tick":{
        "seqId":137005210233,
        "ask":52665.02,
        "askSize":1.502181,
        "bid":52665.01,
        "bidSize":0.178567,
        "quoteTime":1630994555539,
        "symbol":"btcusdt"
    }
}

Update Content

Field Data Type Description
ch string Data belonged channel，Format：market.$symbol.kline.$period
ts long Time of Respond Generation, Unit: Millisecond
<data> object
symbol string Trading symbol
quoteTime long Quote time
bid float Best bid
bidSize float Best bid size
ask float Best ask
askSize float Best ask size
seqId int Sequence number
</data>

Trade Detail

This topic sends the latest completed trades. It updates in tick by tick mode.

Topic

market.$symbol.trade.detail

Subscribe request

{
  "sub": "market.btcusdt.trade.detail",
  "id": "id1"
}

Topic Parameter

Parameter Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol Refer to GET /v1/common/symbols

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.trade.detail",
  "ts": 1489474081631 //system response time
}

Update example

{
    "ch":"market.btcusdt.trade.detail",
    "ts":1630994963175,
    "tick":{
        "id":137005445109,
        "ts":1630994963173,
        "data":[
            {
                "id":137005445109359286410323766,
                "ts":1630994963173,
                "tradeId":102523573486,
                "amount":0.006754,
                "price":52648.62,
                "direction":"buy"
            }
        ]
    }
}

Update Content

Field Data Type Description
ch string Data belonged channel，Format：market.$symbol.trade.detail
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id long global transaction ID
ts long Latest Creation Time
<data> object
id integer Unique trade id (to be obsoleted)
tradeId integer Unique trade id (NEW)
amount float The volume of the trade (buy side or sell side)
price float The price of the trade
ts integer timestamp (UNIX epoch time in millisecond)
direction string direction of the trade (taker): 'buy' or 'sell'
</data>
</tick>

Pull Request

Pull request (of maximum latest 300 trade records) is supported.

{
  "req": "market.btcusdt.trade.detail",
  "id": "id11"
}

Market Details

This topic sends the latest market stats with 24h summary. It updates in snapshot mode, in frequency of no more than 10 times per second.

Topic

market.$symbol.detail

Subscribe request

{
  "sub": "market.btcusdt.detail",
  "id": "id1"
}

Topic Parameter

Parameter Data Type Required Default Value Description Value Range
symbol string true NA Trading symbol Refer to GET /v1/common/symbols

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.detail",
  "ts": 1489474081631 //system response time
}

Update example

{
    "ch":"market.btcusdt.detail",
    "ts":1630998026649,
    "tick":{
        "id":273956868110,
        "low":51000,
        "high":52924.14,
        "open":51823.62,
        "close":52379.99,
        "vol":727676440.200527,
        "amount":13991.028076056185,
        "version":273956868110,
        "count":471348
    }
}

Update Content

Field Data Type Description
ch string Data belonged channel，Format：market.btcusdt.detail
ts long Time of Respond Generation, Unit: Millisecond
<tick> object
id integer UNIX epoch timestamp in second as response id
amount float Aggregated trading volume in past 24H (in base currency)
count integer Number of trades in past 24H
open float Opening price in past 24H
close float Last price
low float Low price in past 24H
high float High price in past 24H
vol float Aggregated trading value in past 24H (in quote currency)
version long version
</tick>

Pull Request

Pull request is supported.

{
  "req": "market.btcusdt.detail",
  "id": "id11"
}

Error Code

Below is the error code, error message and description returned by Market WebSocket

Error Code Error Message Description
bad-request invalid topic Parameter topic is invalid
bad-request invalid symbol Parammeter symbol is invalid
bad-request symbol trade not open now The market is not open for this symbol
bad-request 429 too many request Request exceed limit
bad-request unsub with not subbed topic The topic is not subscribed
bad-request not json string The request is not JSON format
bad-request request timeout The request is time out

Websocket Account and Order

Introduction

Access URL

Websocket Asset and Order

wss://api.huobi.pro/ws/v2

wss://api-aws.huobi.pro/ws/v2

Note: By comparing to api.huobi.pro, the network latency to api-aws.huobi.pro is lower, for those client's servers locating at AWS.

Message Compression

Unlike Market WebSocket, the return data of Account and Order Websocket are not compressed by GZIP.

Heartbeat

{
    "action": "ping",
    "data": {
        "ts": 1575537778295
    }
}

Once the Websocket connection is established, Huobi server will periodically send "ping" message at 20s interval, with an integer inside.

{
    "action": "pong",
    "data": {
          "ts": 1575537778295 // the same with "ping" message
    }
}

Once client receives "ping", it should respond "pong" message back with the same integer.

Valid Values of action

Valid Values Description
sub Subscribe
req Request
ping,pong Heartbeat
push Push (from Huobi server to client's server)

Rate Limit

There are multiple limitations for this version:

Authentication

Authentication request field list

Field Required Data Type Description
action true string Action type, valid value: "req"
ch true string Channel, valid value: "auth"
authType true string Authentication type, valid value: "api". Note: this is not part of signature calculation
accessKey true string Access key
signatureMethod true string Signature method, valid value: "HmacSHA256"
signatureVersion true string Signature version, valid value: "2.1"
timestamp true string Timestamp in UTC in format like 2017-05-11T16:22:06
signature true string Signature 
{
    "action": "req", 
    "ch": "auth",
    "params": { 
        "authType":"api",
        "accessKey": "e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx",
        "signatureMethod": "HmacSHA256",
        "signatureVersion": "2.1",
        "timestamp": "2019-09-01T18:16:16",
        "signature": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o="
    }
}

This is an exmaple of authentication request:

{
    "action": "req",
    "code": 200,
    "ch": "auth",
    "data": {}
}

The response of success:

Generating Signature

The signature generation method of Account and Order WebSocket is similar with Rest API , with only following differences:

  1. The request method should be "GET", to URL "/ws/v2".
  2. The involved field names in signature generation are: accessKey，signatureMethod，signatureVersion，timestamp
  3. The valid value of signatureVersion is 2.1.

Please refer to detailed signature generation steps from: [https://huobiapi.github.io/docs/spot/v1/cn/#c64cd15fdc]

GET\n api.huobi.pro\n /ws/v2\n accessKey=0664b695-rfhfg2mkl3-abbf6c5d-49810&signatureMethod=HmacSHA256&signatureVersion=2.1&timestamp=2019-12-05T11%3A53%3A03

The final string involved in signature generation should be like below:

Note: The data in JSON request doesn't require URL encode

Subscribe a Topic to Continuously Receive Updates

Once the Websocket connection is established, Websocket client could send following request to subscribe a topic:

{
"action": "sub",
"ch": "accounts.update"
}

Upon success, Websocket client should receive a response below:

{
"action": "sub",
"code": 200,
"ch": "accounts.update#0",
"data": {}
}

first push msg of accounts update exception

{
"action":"sub",
"code":500,
"ch":"accounts.update#2",
"message":"系统异常:"
}

When the first push msg is "message":"系统异常:", accounts update infotmation will not be pushed any more, and you need to re-subscribe accounts update topic

Subscribe Order Updates

API Key Permission: Read

An order update can be triggered by any of following:
- Conditional order triggering failure (eventType=trigger)
- Conditional order cancellation before trigger (eventType=deletion)
- Order creation (eventType=creation)
- Order matching (eventType=trade)
- Order cancellation (eventType=cancellation)

The field list in order update message can be various per event type, developers can design the data structure in either of two ways:
- Define a data structure including fields for all event types, allowing a few of them are null
- Define different data structure for each event type to include specific fields, inheriting from a common data structure which has common fields

Topic

orders#${symbol}

Subscribe request

{
    "action": "sub",
    "ch": "orders#btcusdt"
}

Response

{
    "action": "sub",
    "code": 200,
    "ch": "orders#btcusdt",
    "data": {}
}

Subscription Field

Field Data Type Description
symbol string Trading symbol (wildcard * is allowed)

Update Content

{
    "action":"push",
    "ch":"orders#btcusdt",
    "data":
     {
        "orderSide":"buy",
        "lastActTime":1583853365586,
        "clientOrderId":"abc123",
        "orderStatus":"rejected",
        "symbol":"btcusdt",
        "eventType":"trigger",
        "errCode": 2002,
        "errMessage":"invalid.client.order.id (NT)"
    }
}

After conditional order triggering failure –

Field Data Type Description
eventType string Event type, valid value: trigger (only applicable for conditional order)
symbol string Trading symbol
clientOrderId string Client order ID
orderSide string Order side, valid value: buy, sell
orderStatus string Order status, valid value: rejected
errCode int Error code for triggering failure
errMessage string Error message for triggering failure
lastActTime long Order triggering failure time 
{
    "action":"push",
    "ch":"orders#btcusdt",
    "data":
    {
        "orderSide":"buy",
        "lastActTime":1583853365586,
        "clientOrderId":"abc123",
        "orderStatus":"canceled",
        "symbol":"btcusdt",
        "eventType":"deletion"
    }
}

After conditional order being cancelled before triggering –

Field Data Type Description
eventType string Event type, valid value: deletion (only applicable for conditional order)
symbol string Trading symbol
clientOrderId string Client order ID
orderSide string Order side, valid value: buy, sell
orderStatus string Order status, valid value: canceled
lastActTime long Order trigger time 
{
    "action":"push",
    "ch":"orders#btcusdt",
    "data":
    {
        "orderSize":"2.000000000000000000",
        "orderCreateTime":1583853365586,
        "accountld":992701,
        "orderPrice":"77.000000000000000000",
        "type":"sell-limit",
        "orderId":27163533,
        "clientOrderId":"abc123",
        "orderSource":"spot-api",
        "orderStatus":"submitted",
        "symbol":"btcusdt",
        "eventType":"creation"

    }
}

After order is submitted –

Field Data Type Description
eventType string Event type, valid value: creation
symbol string Trading symbol
accountId long account ID
orderId long Order ID
clientOrderId string Client order ID (if any)
orderSource string Order source
orderPrice string Order price
orderSize string Order size (inapplicable for market buy order)
orderValue string Order value (only applicable for market buy order)
type string Order type, valid value: buy-market, sell-market, buy-limit, sell-limit, buy-limit-maker, sell-limit-maker, buy-ioc, sell-ioc, buy-limit-fok, sell-limit-fok
orderStatus string Order status, valid value: submitted
orderCreateTime long Order creation time

Note:
- If a stop limit order is created but not yet triggered, the topic won’t send an update.
- The topic will send creation update for taker's order before it being filled.
- Stop limit order's type is no longer as "buy-stop-limit" or "sell-stop-limit", but changing to "buy-limit" or "sell-limit".

{
    "action":"push",
    "ch":"orders#btcusdt",
    "data":
    {
        "tradePrice":"76.000000000000000000",
        "tradeVolume":"1.013157894736842100",
        "tradeId":301,
        "tradeTime":1583854188883,
        "aggressor":true,
        "remainAmt":"0.000000000000000400000000000000000000",
        "execAmt":"2",
        "orderId":27163536,
        "type":"sell-limit",
        "clientOrderId":"abc123",
        "orderSource":"spot-api",
        "orderPrice":"15000",
        "orderSize":"0.01",
        "orderStatus":"filled",
        "symbol":"btcusdt",
        "eventType":"trade"
    }
}

After order matching –

Field Data Type Description
eventType string Event type, valid value: trade
symbol string Trading symbol
tradePrice string Trade price
tradeVolume string Trade volume
orderId long Order ID
type string Order type, valid value: buy-market, sell-market, buy-limit, sell-limit, buy-limit-maker, sell-limit-maker, buy-ioc, sell-ioc, buy-limit-fok, sell-limit-fok
clientOrderId string Client order ID (if any)
orderSource string Order source
orderPrice string Original order price (not available for market order)
orderSize string Original order amount (not available for buy-market order)
orderValue string Original order value (only available for buy-market order)
tradeId long Trade ID
tradeTime long Trade time
aggressor bool Aggressor or not, valid value: true (taker), false (maker)
orderStatus string Order status, valid value: partial-filled, filled
remainAmt string Remaining amount (for buy-market order it's remaining value)
execAmt string Accumulative amount (for buy-market order it is accumulative value)

Note:
- Stop limit order's type is no longer as "buy-stop-limit" or "sell-stop-limit", but changing to "buy-limit" or "sell-limit".
- If a taker’s order matching with multiple orders at opposite side simultaneously, the multiple trades will be disseminated over separately instead of merging into one trade.

{
    "action":"push",
    "ch":"orders#btcusdt",
    "data":
    {
        "lastActTime":1583853475406,
        "remainAmt":"2.000000000000000000",
        "execAmt":"2",
        "orderId":27163533,
        "type":"sell-limit",
        "clientOrderId":"abc123",
        "orderSource":"spot-api",
        "orderPrice":"15000",
        "orderSize":"0.01",
        "orderStatus":"canceled",
        "symbol":"btcusdt",
        "eventType":"cancellation"
    }
}

After order cancellation –

Field Data Type Description
eventType string Event type, valid value: cancellation
symbol string Trading symbol
orderId long Order ID
type string Order type, valid value: buy-market, sell-market, buy-limit, sell-limit, buy-limit-maker, sell-limit-maker, buy-ioc, sell-ioc, buy-limit-fok, sell-limit-fok
clientOrderId string Client order ID (if any)
orderSource string Order source
orderPrice string Original order price (not available for market order)
orderSize string Original order amount (not available for buy-market order)
orderValue string Original order value (only available for buy-market order)
orderStatus string Order status, valid value: partial-canceled, canceled
remainAmt string Remaining amount (for buy-market order it's remaining value)
execAmt string Accumulative amount (for buy-market order it is accumulative value)
lastActTime long Last activity time

Note:
- Stop limit order's type is no longer as "buy-stop-limit" or "sell-stop-limit", but changing to "buy-limit" or "sell-limit".

Subscribe Trade Details & Order Cancellation post Clearing

API Key Permission: Read

Only update when order is in transaction or cancellation. Order transaction update is in tick by tick mode, which means, if a taker’s order matches with multiple maker’s orders, the simultaneous multiple trades will be disseminated one by one. But the update sequence of the multiple trades, may not be exactly the same as the sequence of the transactions made. Also, if an order is auto cancelled immediately just after its partial fills, for example a typical IOC order, this channel would possibly disseminate the cancellation update first prior to the trade.

If user willing to receive order updates in exact same sequence with the original happening, it is recommended to subscribe order update channel orders#${symbol}.

Topic

trade.clearing#${symbol}#${mode}

Subscription Field

Field Data Type Description
symbol string Trading symbol (wildcard * is allowed)
mode int Subscription mode (0 – subscribe only trade event; 1 – subscribe both trade and cancellation events; default value: 0)

Note:
About optional field ‘mode’: If not filled, or filled with 0, it implicates to subscribe trade event only. If filled with 1, it implicates to subscribe both trade and cancellation events.

Subscribe request

{
    "action": "sub",
    "ch": "trade.clearing#btcusdt#0"
}

Response

{
    "action": "sub",
    "code": 200,
    "ch": "trade.clearing#btcusdt#0",
    "data": {}
}

Update example

{
    "ch": "trade.clearing#btcusdt#0",
    "data": {
         "eventType": "trade",
         "symbol": "btcusdt",
         "orderId": 99998888,
         "tradePrice": "9999.99",
         "tradeVolume": "0.96",
         "orderSide": "buy",
         "aggressor": true,
         "tradeId": 919219323232,
         "tradeTime": 998787897878,
         "transactFee": "19.88",
         "feeDeduct ": "0",
         "feeDeductType": "",
         "feeCurrency": "btc",
         "accountId": 9912791,
         "source": "spot-api",
         "orderPrice": "10000",
         "orderSize": "1",
         "clientOrderId": "a001",
         "orderCreateTime": 998787897878,
         "orderStatus": "partial-filled"
    }
}

Update Contents (after order matching)

Field Data Type Description
eventType string Event type (trade)
symbol string Trading symbol
orderId long Order ID
tradePrice string Trade price
tradeVolume string Trade volume
orderSide string Order side, valid value: buy, sell
orderType string Order type, valid value: buy-market, sell-market,buy-limit,sell-limit,buy-ioc,sell-ioc,buy-limit-maker,sell-limit-maker,buy-stop-limit,sell-stop-limit,buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok
aggressor bool Aggressor or not, valid value: true, false
tradeId long Trade ID
tradeTime long Trade time, unix time in millisecond
transactFee string Transaction fee (positive value) or Transaction rebate (negative value)
feeCurrency string Currency of transaction fee or transaction fee rebate (transaction fee of buy order is based on base currency, transaction fee of sell order is based on quote currency; transaction fee rebate of buy order is based on quote currency, transaction fee rebate of sell order is based on base currency)
feeDeduct string Transaction fee deduction
feeDeductType string Transaction fee deduction type, valid value: ht, point
accountId long Account ID
source string Order source
orderPrice string Order price (invalid for market order)
orderSize string Order size (invalid for market buy order)
orderValue string Order value (only valid for market buy order)
clientOrderId string Client order ID
stopPrice string Stop price (only valid for stop limit order)
operator string Operation character (only valid for stop limit order)
orderCreateTime long Order creation time
orderStatus string Order status, valid value: filled, partial-filled

Notes:
- The calculated maker rebate value inside ‘transactFee’ may not be paid immediately.

Update Contents (after order cancellation)

Field Data Type Description
eventType string Event type (cancellation)
symbol string Trading symbol
orderId long Order ID
orderSide string Order side, valid value: buy, sell
orderType string Order type, valid value: buy-market, sell-market,buy-limit,sell-limit,buy-ioc,sell-ioc,buy-limit-maker,sell-limit-maker,buy-stop-limit,sell-stop-limit,buy-limit-fok, sell-limit-fok, buy-stop-limit-fok, sell-stop-limit-fok
accountId long Account ID
source string Order source
orderPrice string Order price (invalid for market order)
orderSize string Order size (invalid for market buy order)
orderValue string Order value (only valid for market buy order)
clientOrderId string Client order ID
stopPrice string Stop price (only valid for stop limit order)
operator string Operation character (only valid for stop limit order)
orderCreateTime long Order creation time
remainAmt string Remaining order amount (if market buy order, it implicates remaining order value)
orderStatus string Order status, valid value: canceled, partial-canceled

Subscribe Account Change

API Key Permission: Read

The topic updates account change details.

Topic

accounts.update#${mode}

Upon subscription field value specified, the update can be triggered by either of following events:

1、Whenever account balance is changed.

2、Whenever account balance or available balance is changed. (Update separately.)

3、Whenever account balance or available balance changed, it will be updated together.

Note that right now there is no account update when transferring between spot account and other accounts.

Subscription Field

Field Data Type Description
mode integer Trigger mode, valid value: 0, 1, default value: 0

Samples

1、Not specifying "mode":
accounts.update
Only update when account balance changed;

2、Specify "mode" as 0:
accounts.update#0
Only update when account balance changed;

3、Specify "mode" as 1:
accounts.update#1
Update when either account balance changed or available balance changed.

4、Specify "mode" as 2:
accounts.update#2
Whenever account balance or available balance changed, it will be updated together.

Note: The topic disseminates the current static value of individual accounts first, at the beginning of subscription, followed by account change updates. While disseminating the current static value of individual accounts, inside the message, field value of "changeType" and "changeTime" is null.

Subscribe request

{
    "action": "sub",
    "ch": "accounts.update"
}

Response

{
    "action": "sub",
    "code": 200,
    "ch": "accounts.update#0",
    "data": {}
}

Update example

accounts.update#0：
{
    "action": "push",
    "ch": "accounts.update#0",
    "data": {
        "currency": "btc",
        "accountId": 123456,
        "balance": "23.111",
        "changeType": "transfer",
        "accountType":"trade",
        "seqNum": "86872993928",
        "changeTime": 1568601800000
    }
}

accounts.update#1：
{
    "action": "push",
    "ch": "accounts.update#1",
    "data": {
        "currency": "btc",
        "accountId": 33385,
        "available": "2028.699426619837209087",
        "changeType": "order.match",
        "accountType":"trade",
        "seqNum": "86872993928",
        "changeTime": 1574393385167
    }
}
{
    "action": "push",
    "ch": "accounts.update#1",
    "data": {
        "currency": "btc",
        "accountId": 33385,
        "balance": "2065.100267619837209301",
        "changeType": "order.match",
        "accountType":"trade",
        "seqNum": "86872993928",
        "changeTime": 1574393385122
    }
}

Update Contents

Field Data Type Description
currency string Currency
accountId long Account ID
balance string Account balance (only exists when account balance changed)
available string Available balance (only exists when available balance changed)
changeType string Change type, valid value: order-place,order-match,order-refund,order-cancel,order-fee-refund,margin-transfer,margin-loan,margin-interest,margin-repay,deposit,withdraw,other
accountType string account type, valid value: trade, loan, interest
changeTime long Change time, unix time in millisecond
seqNum long Serial Number of Account Change

Note:

Error Code

Below is the return code, return message and the description returend from Asset and Order WebSocket

Return Code Return Message Description
200 Success Successful
100 time out close The connection is timeout and closed
400 Bad Request The request is invalid
404 Not Found The service is not found
429 Too Many Requests Connection number exceed limit
500 system error System internal error
2000 invalid.ip The IP is invalid
2001 nvalid.json The JSON request is invalid
2001 invalid.action Parameter action is invalid
2001 invalid.symbol Parameter symbol is invalid
2001 invalid.ch Parameter channel is invalid
2001 missing.param.auth Parameter auth is missing
2002 invalid.auth.state Authentication state is invalid
2002 auth.fail Authentication failed, including wrong IP address binding in API Key
2003 query.account.list.error Account query error
4000 too.many.request Request exceed limit (a single instance limit to 50 per second)
4000 too.many.connection Connection number exceed limit for single API Key (a single instance limit to 10 connections)

Will be offline

Get all Supported Trading Symbol(V1)(deprecated)

This endpoint returns all Huobi's supported tradable symbols.

curl "https://api.huobi.pro/v1/common/symbols"

HTTP Request

Request Parameters

No parameter is needed for this endpoint.

Responds:

{
    "status":"ok",
    "data":[
        {
            "base-currency":"btc3l",
            "quote-currency":"usdt",
            "price-precision":4,
            "amount-precision":4,
            "symbol-partition":"main",
            "symbol":"btc3lusdt",
            "state":"online",
            "value-precision":8,
            "min-order-amt":0.01,
            "max-order-amt":199.0515,
            "min-order-value":5,
            "limit-order-min-order-amt":0.01,
            "limit-order-max-order-amt":199.0515,
            "limit-order-max-buy-amt":199.0515,
            "limit-order-max-sell-amt":199.0515,
            "buy-limit-must-less-than":1.1,
            "sell-limit-must-greater-than":0.9,
            "sell-market-min-order-amt":0.01,
            "sell-market-max-order-amt":199.0515,
            "buy-market-max-order-value":2500,
            "market-sell-order-rate-must-less-than":0.1,
            "market-buy-order-rate-must-less-than":0.1,
            "max-order-value":2500,
            "underlying":"btcusdt",
            "mgmt-fee-rate":0.035,
            "charge-time":"23:55:00",
            "rebal-time":"00:00:00",
            "rebal-threshold":4,
            "init-nav":16.3568,
            "api-trading":"enabled",
            "tags":"etp,nav,holdinglimit,activities"
        }
    ]
}

Response Content

Parameter Required Data Type Description
status true string Request Processing Result（"ok","error"）
<data> true object
base-currency true string Base currency in a trading symbol
quote-currency true string Quote currency in a trading symbol
price-precision true integer Quote currency precision when quote price(decimal places)）
amount-precision true integer Base currency precision when quote amount(decimal places)）
symbol-partition true string Trading section, possible values: [main，innovation]
symbol true string symbol
state true string The status of the symbol；Allowable values: [online，offline,suspend]. "online" - Listed, available for trading, "offline" - de-listed, not available for trading， "suspend"-suspended for trading, "pre-online" - to be online soon
value-precision true integer Precision of value in quote currency (value = price * amount)
min-order-amt true float Minimum order amount of limit order in base currency (to be obsoleted)
max-order-amt true float Max order amount of limit order in base currency (to be obsoleted)
limit-order-min-order-amt true float Minimum order amount of limit order in base currency (NEW)
limit-order-max-order-amt true float Max order amount of limit order in base currency (NEW)
sell-market-min-order-amt true float Minimum order amount of sell-market order in base currency (NEW)
sell-market-max-order-amt true float Max order amount of sell-market order in base currency (NEW)
buy-market-max-order-value true float Max order value of buy-market order in quote currency (NEW)
min-order-value true float Minimum order value of limit order and buy-market order in quote currency
max-order-value false float Max order value of limit order and buy-market order in usdt (NEW)
buy-limit-must-less-than false decimal(10,6) Buy limit must less than
sell-limit-must-greater-than false decimal(10,6) Sell limit must greater than
market-sell-order-rate-must-less-than false decimal(10,6) Market sell order rate must less than
market-buy-order-rate-must-less-than false decimal(10,6) Market buy order rate must less than
leverage-ratio true float The applicable leverage ratio (only valid for symbols eligible for isolated margin trading, cross-margin trading, or ETP trading.)
underlying false string Underlying ETP code (only valid for ETP symbols)
mgmt-fee-rate false float Position charging rate (only valid for ETP symbols)
charge-time false string Position charging time (in GMT+8, in format HH:MM:SS, only valid for ETP symbols)
rebal-time false string Regular position rebalance time (in GMT+8, in format HH:MM:SS, only valid for ETP symbols)
rebal-threshold false float The threshold which triggers adhoc position rebalance (evaluated by actual leverage ratio, only valid for ETP symbols)
init-nav false float Initial NAV (only valid for ETP symbols)
api-trading true string API trading enabled or not (possible value: enabled, disabled)
ca-state false string the state of the call auction; it will only be displayed when it is in the 1st and 2nd stage of the call auction. Enumeration values: "ca_1", "ca_2"
</data>

Get all Supported Currencies(V1)(deprecated)

This endpoint returns all Huobi's supported tradable currencies.

curl "https://api.huobi.pro/v1/common/currencys"

HTTP Request

Request Parameters

No parameter is needed for this endpoint.

Response:

{
    "status": "ok",
    "data": [
        "usdt",
        "btc",
        "bch",
        "eth",
        "xrp",
        "ltc",
        "ht",
        "ada"
    ]
}

Response Content

Field Name Required Data Type Description
status true string Request Processing Result（"ok","error"）
data true array with each string represents a suppported currency
json