# Huobi Python SDK: a thin client per data category, REST and WebSocket

> The huobi_Python SDK gives you one small client class per API category, so public market data and private account actions are separated by construction rather than by a flag, and the market, account and trade clients also stream updates over WebSocket. It is Apache-2.0 licensed, and its packaging metadata still says version 2.0.1 while the newest release is v3.0.2 from 2024.

**HuobiRDCenter/huobi_Python** — Python SDK for Huobi Spot API

- Repository: https://github.com/HuobiRDCenter/huobi_Python
- Website: https://huobiapi.github.io/docs/spot/v1/en
- Stars: 686 · Forks: 319
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/huobirdcenter-huobi-python

## One client per category, and why that split is the design

The Huobi Python SDK v3 lets you query market data, trade and manage your account. It supports invoking the RESTful API and, concurrently, subscribing to market, account and order updates over a WebSocket connection.

The organising idea is that the client category matches the API category, and the README says this is done in order to isolate private data from public data and to isolate different kinds of data from each other. The consequence is visible in the client table. GenericClient and MarketClient are public, and everything else is private.

| Data Category | Client | Privacy | Protocol |
| Generic | GenericClient | Public | Rest |
| Market | MarketClient | Public | Rest, WebSocket |
| Account | AccountClient | Private | Rest, WebSocket v2 |
| Wallet | WalletClient | Private | Rest |
| Trade | TradeClient | Private | Rest, WebSocket v2 |
| Margin | MarginClient | Private | Rest |
| Sub User | SubuserClient | Private | Rest |
| Algo | AlgoClient | Private | Rest |
| ETF | ETFClient | Private | Rest |

Each client is described as very small and simple, responsible only for operating its related data, and you pick multiple clients to build your own application around your business. That is a small design decision with a real effect on how the SDK gets used: a public data path and a private trading path are different objects, and a bug in one is not a bug in the other.

The protocol column matters as much. Market data arrives over REST and WebSocket, and account and trade updates stream over a WebSocket v2 channel, while wallet, margin, sub user, algo and ETF operations are REST only. So the streaming capability is narrow by category, and the README's subscription examples cover trade, candlestick, order and account updates.

## A first call needs no credentials at all

The quick start is two steps: create the client instance, then call the interfaces the client provides. The example creates a generic client to read the exchange timestamp and a market client to pull the latest candlesticks for a symbol:

```python
# Create generic client instance and get the timestamp
generic_client = GenericClient()
ts = generic_client.get_exchange_timestamp()
print(timestamp)

# Create the market client instance and get the latest btcusdt‘s candlestick
market_client = MarketClient()
list_obj = market_client.get_candlestick("btcusdt", CandlestickInterval.MIN5, 10)
LogInfo.output_list(list_obj)
```

The interval is an enum rather than a string, so the supported periods are discoverable from the code, and the size argument caps how many candles come back. The example then hands the result to LogInfo, which belongs to the utility layer.

The SDK is compiled by Python 3.7 and above, and the README is explicit that you download the source and place it in your project rather than installing it from a package index. The steps are to create the client instance and call the interfaces it provides.

The example as printed contains a small inconsistency, since the timestamp is assigned to ts and then print(timestamp) refers to a different name, so running it as written would raise a NameError unless something else defines that name. It is worth knowing that before you paste it into a script.

The public clients need no key at all. A public client invokes the public API to get public data, generic and market, so you can create an instance without applying for an API key.

## Private clients, the key file, and customised hosts

Accessing private data means applying for an API key from the exchange's website, then passing the key and secret to the client constructor:

```python
// Create an AccountClient instance with APIKey
account_client = AccountClient(api_key=g_api_key, secret_key=g_secret_key)

// Create a TradeClient instance with API Key and customized host
trade_client = TradeClient(api_key=g_api_key, secret_key=g_secret_key, url="https://api-aws.huobi.pro")
```

The key is used for authentication, and if the authentication cannot pass then the invoking of the private interface fails. That sentence is the whole error story the README gives you, so in practice an auth failure shows up as a failed private call rather than a distinct exception type, and the exception package in the source tree is where you would look for the detail.

The key handling has a specific convention that is worth copying even if you do not use this SDK. To run the private examples you create a privateconfig.py file inside the huobi folder, with the purpose of preventing the secret key from being submitted into the repository by accident, and that file is already added to the gitignore:

```python
p_api_key = "hrf5gdfghe-e74bebd8-2f4a33bc-e7963"
p_secret_key = "fecbaab2-35befe7e-2ea695e8-67e56"
```

The client classes also support a customised host, so you can define your own endpoint, and the example shows it applied to a market client:

```python
// Create a GenericClient instance
generic_client = GenericClient()

// Create a MarketClient instance with customized host
market_client = MarketClient(url="https://api-aws.huobi.pro")
```

That is the escape hatch for regional or alternative endpoints, and it matters more than it looks: a hardcoded default host is a single point of failure for anything running in production.

## Inside the package: connection, model, service, utils

The README documents the folder structure of the SDK source, and it describes a layered design that is conventional for exchange SDKs.

The huobi package is the core. Inside it, client is the external interface layer responsible for accessing data, connection manages the remote server connection, constant holds the constant configuration, exception holds the wrapped exception, model holds the server returned data model, service is the internal implementation for each client, and utils holds the utility classes including signature, json parser and logging.

The split between service and model is the one to understand. A service is the internal implementation behind a client, and a model is the typed representation of what the server returned. So a caller works with client and model, and never touches the HTTP layer directly. The utils entry tells you the other half of the story: signing, parsing and logging are utility concerns, not scattered across services.

Outside the core package, performance is for internal performance testing and tests is for internal functional testing. The example directory carries one subdirectory per client category, and the README describes it as the main package, providing examples of how to use a client instance to access the API and read the response.

So the source tree reads as a reference implementation with its own test and performance harnesses included. That is a good sign for a library you intend to read before trusting, since the examples and the tests are in the same repository as the code.

## Version 3 versus the older lines, and where the project stands

The README is unusually direct about the version history, and that is useful information rather than marketing. If you already use SDK v1 or v2, it is strongly suggested that you migrate to v3, because the implementation was refactored to be simpler and easier to maintain.

The reasons given are specific. The v3 line is completely consistent with the API documentation of the new HTX open platform, and because many interfaces changed their parameters, v3 adjusted the parameters of more than 80 interfaces so that requests can be correctly initiated and accurate response data obtained. It also added over 130 new interfaces. And the maintainers state that they will stop maintaining v2 in the near future.

The date picture is worth recording. The tagged releases are v3.0.2 from 2024-07-15, v3.0.1 from 2024-05-21 and v3 from 2024-03-05. The last push to the repository was on 2026-04-11, and the repository is not archived, so the code is still being changed.

There is an inconsistency in the packaging. The setup.py in the repository declares name huobi-client at version 2.0.1, while the released line is v3, and its install_requires are requests, apscheduler, websocket-client and urllib3. The requirements.txt pins different and older versions again: APScheduler 3.6.3, requests 2.20.1, aiohttp 3.6.2 and websocket_client 0.57.0. So the package metadata, the requirements file and the release tags do not describe the same thing.

That matters if you install from a package index rather than vendoring the source. requests 2.20.1 in particular is an old pin, and the repository has a .travis.yml for continuous integration, which dates the setup.

## Where this SDK is the wrong choice

The first limitation is scope. This is a spot SDK. The description says Python SDK for Huobi Spot API, and the client table covers generic, market, account, wallet, trade, margin, sub user, algo and ETF. The margin client exists but is REST only, and there is nothing here for futures, options or any other product line. If your strategy is not spot, the client you need is not here.

The second limitation is the age of the pins. The requirements file holds requests 2.20.1 and aiohttp 3.6.2, which are years behind current releases, and the setup.py carries a version string of 2.0.1 against a v3 release line. Vendoring the source avoids the version metadata problem, but it does not avoid the old dependency pins, and those pins are what a security review of your project will find.

The third limitation is that this is a single-exchange SDK, so the abstraction stops at the exchange boundary. There is no unified interface to switch venues, no normalised error taxonomy, no retry or rate limit policy, and no test suite that runs against a recorded API fixture. The signing is in the utils layer, the models are this exchange's models, and the client names are this exchange's categories. If your plan involves more than one venue, you will end up writing that layer yourself.

The real alternative, and it is the direction most serious trading code goes, is to write against the raw HTTP API using requests or httpx and a signing library, and to generate your own data models. The difference in approach is that you get control of the request pipeline, the retry behaviour, the rate limit handling and the type layer, at the cost of reimplementing signing, pagination and the response models for every endpoint you touch. For a handful of endpoints, that is the cheaper option. For the eighty-plus interfaces this SDK already covers, and for the WebSocket subscriptions with their own message formats, the SDK is doing real work, and the honest cost of using it is the old pins and the coupling to one exchange's naming.

## Conclusion

Adopt the Huobi Python SDK if you are building a spot trading service on this exchange and want the request signing, response models and WebSocket subscriptions already implemented, and if you can live with an SDK whose release line stopped in 2024. Do not adopt it for futures, margin trading beyond the covered endpoints or anything other than spot, and do not treat it as a long-lived dependency without checking what the exchange has changed since. Before you build on it, confirm the client list in the README still matches the endpoints the platform currently serves, verify the pinned dependency versions in requirements.txt against your own environment, and put the API key in the gitignored privateconfig.py rather than in your source.

## FAQ

### What is the Huobi Python SDK?

It is the Python SDK v3 for the Huobi Spot API, letting you query market data, trade and manage your account. It supports invoking the RESTful API and concurrently subscribing to market, account and order updates over a WebSocket connection, and it is published under the Apache-2.0 licence.

### Do I need an API key to get market data from the Huobi Python SDK?

No. Public clients, which are GenericClient and MarketClient, invoke the public API and can be created without applying for an API key. Private clients such as AccountClient and TradeClient need the key and secret passed to their constructor, and a private call fails if the authentication does not pass.

### How do I keep my Huobi API secret out of version control?

The SDK's convention is to create a privateconfig.py file inside the huobi folder holding the api_key and secret_key values, and that file is already listed in the gitignore so the secret cannot be committed by accident. You import the values from there when constructing a private client.

### Which Huobi Python SDK clients support WebSocket?

The client table shows MarketClient, AccountClient and TradeClient with WebSocket in the protocol column, with the account and trade clients on WebSocket v2. The remaining clients, covering generic, wallet, margin, sub user, algo and ETF data, are REST only.

### What is the current state of the Huobi Python SDK?

The tagged releases are v3.0.2 from 2024-07-15, v3.0.1 from 2024-05-21 and v3 from 2024-03-05, the repository is not archived, and the last push was on 2026-04-11. The README says the maintainers will stop maintaining v2 in the near future, and the setup.py in the repository still declares version 2.0.1 with older dependency pins than the v3 release line.

## Sources

- [HuobiRDCenter/huobi_Python on GitHub](https://github.com/HuobiRDCenter/huobi_Python)
- [License: Apache-2.0](https://github.com/HuobiRDCenter/huobi_Python/blob/master/LICENSE)
- [Project website](https://huobiapi.github.io/docs/spot/v1/en)
- [README](https://github.com/HuobiRDCenter/huobi_Python/blob/master/README.md)
- [Releases](https://github.com/HuobiRDCenter/huobi_Python/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/huobirdcenter-huobi-python