> For the complete documentation index, see [llms.txt](https://hertzflow.gitbook.io/hertzflow-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hertzflow.gitbook.io/hertzflow-docs/tech-docs/api.md).

# API

HertzFlow provides public REST APIs for reading protocol and product data on **BNB Smart Chain (BSC)**.

* **Data & Statistics** — markets, prices, user activity, vaults, pools, leaderboard, and dashboard
* **Kline Query** — historical candlestick (OHLCV) data

All documented routes are public `GET` endpoints. They do not submit transactions.

## On this page

* [Base URLs](#base-urls)
* [Authentication](#authentication)
* [Rate limits, pagination, and sorting](#rate-limits-pagination-and-sorting)
* [Numeric encoding](#numeric-encoding)
* [Response envelope](#response-envelope)
* [Errors](#errors)
* [Quick start](#quick-start)
* [Glossary](#glossary)

## Base URLs

| Service           | Network     | Base URL                                           |
| ----------------- | ----------- | -------------------------------------------------- |
| Data & Statistics | BSC Testnet | `https://data-statistics-query.testnet.htzfl.link` |
| Kline Query       | BSC Testnet | `https://kline-query.testnet.htzfl.link`           |

Unless noted otherwise, every endpoint in the [API Reference](/hertzflow-docs/tech-docs/api/api-reference.md) uses the Data & Statistics base URL. The Kline endpoint uses the Kline Query base URL.

## Authentication

No authentication, API key, or authorization header is required.

## Rate limits, pagination, and sorting

Official rate limits are not published yet. Avoid bursting requests; retry with exponential backoff if a call fails.

List endpoints use either **cursor pagination** (`cursor`, `limit`) or **offset pagination** (`page`, `page_size`); see each endpoint in the [API Reference](/hertzflow-docs/tech-docs/api/api-reference.md).

Time-series endpoints (vault charts, pool charts, dashboard charts) accept period or range query parameters. Names vary by endpoint — see the [API Reference](/hertzflow-docs/tech-docs/api/api-reference.md).

## Numeric encoding

Many numeric fields are returned as **strings** to preserve precision. Encoding can differ by field — check the field description in the [API Reference](/hertzflow-docs/tech-docs/api/api-reference.md).

* **Prices** (for example `open_24h`, `current_price`, candle OHLC) — human-readable decimal strings, e.g. `"65498.93658727"`.
* **USD amounts — two encodings coexist:**
  * **1e30 fixed-point integers** — used by vault/pool and trade fields such as `tvl`, `tvl_usd`, `supply`, `fees_30d`, `capacity.*`, `max_cap`, `size_*_usd`, and `pnl_detail.*`. Here `1e30` represents `1.0`, e.g. `"1807943250804061767573075264685426426"` ≈ 1807.94 USD.
  * **Human-readable decimal strings** — used by dashboard and leaderboard fields such as `total_volume`, leaderboard `volume`, `total_users`, and `total_fees`, e.g. `"3456155907.08"`.
* **Token amounts** (for example `size_in_tokens`, `collateral_delta_amount`) — integers scaled by the token's own decimals.

## Response envelope

Successful responses use this JSON shape:

```json
{
  "code": 200,
  "msg": "",
  "data": {}
}
```

The Kline endpoint may also include `is_success: true` at the top level.

## Errors

| HTTP status | Description                |
| ----------- | -------------------------- |
| `200`       | Success                    |
| `400`       | Invalid request parameters |
| `404`       | Resource not found         |
| `500`       | Internal server error      |

On error the body keeps the same shape: a non-success `code`, a `msg` describing the failure, and usually empty `data`. The Kline endpoint, however, returns a different error shape: `error`, `error_code`, and `is_success: false` (for example `{"code":400,"error":"must specify time range","error_code":"INVALID_PARAMS_ERROR","is_success":false}`).

## Quick start

Fetch the market list:

```bash
curl "https://data-statistics-query.testnet.htzfl.link/api/v1/bsc/markets"
```

Example response (truncated):

```json
{
  "code": 200,
  "msg": "",
  "data": {
    "markets": [
      {
        "symbol": "BTC/USD",
        "display_name": "BTC/USD",
        "px_disp_decimal": 2,
        "category": "crypto",
        "max_leverage_normal": 50,
        "min_leverage_hyper": 84,
        "max_leverage_hyper": 200,
        "market_address": "0x672859847c107200f8a8089b8b4d25f78b3a041e",
        "index_token_address": "0x2d8f28f05113c2dc0a17ebbba60d8f72318bdb1f",
        "long_token_address": "0x22527bb489a0c7d91f63e63226b14f979f5ff090",
        "short_token_address": "0x22527bb489a0c7d91f63e63226b14f979f5ff090",
        "schedule": "America/New_York;O,O,O,O,O,O,O;",
        "is_view": true,
        "is_market_pausing": false,
        "is_default": false
      }
    ]
  }
}
```

More examples:

```bash
# 24-hour price statistics
curl "https://data-statistics-query.testnet.htzfl.link/api/v1/bsc/prices/24h"

# User trades (cursor pagination)
curl "https://data-statistics-query.testnet.htzfl.link/api/v1/bsc/user/trades?user_address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0&cursor=&limit=20"

# Historical candlesticks (Kline Query service)
curl "https://kline-query.testnet.htzfl.link/api/v1/historyKLines?symbol=ETH/USD&interval=15m&start_time=1785994200&end_time=1785995100&limit=10"
```

For the full endpoint list, see the [API Reference](/hertzflow-docs/tech-docs/api/api-reference.md).

## Glossary

| Term              | Meaning                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **BSC**           | BNB Smart Chain                                                                               |
| **OHLCV**         | Open / High / Low / Close / Volume                                                            |
| **PnL**           | Profit and Loss                                                                               |
| **OI**            | Open Interest                                                                                 |
| **GLV / HzV**     | HertzFlow vault contracts                                                                     |
| **HzLP**          | HertzFlow liquidity-provider (pool) market                                                    |
| **1e30 encoding** | Fixed-point integer where `1e30` represents `1.0` (see [Numeric encoding](#numeric-encoding)) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hertzflow.gitbook.io/hertzflow-docs/tech-docs/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.