> 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

## Base URLs

#### BSC Testnet

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

The **Data & Statistics** service serves markets, prices, and user trade history. The **Kline Query** service serves historical candlestick data.

## API Endpoints

| API           | Method & Endpoint             | Description                                          |
| ------------- | ----------------------------- | ---------------------------------------------------- |
| Market List   | `GET /api/v1/bsc/markets`     | List all markets with leverage, OI, and 24h stats    |
| Latest Price  | `GET /api/v1/bsc/prices/24h`  | 24h high/low/open + current price for all markets    |
| User Activity | `GET /api/v1/bsc/user/trades` | Cursor-paginated trade/position history for a wallet |
| Kline         | `GET /api/v1/historyKLines`   | Historical candlestick/OHLCV data                    |

> The Market List, Latest Price, and User Activity endpoints live under the **Data & Statistics** base URL. The Kline endpoint lives under the **Kline Query** base URL.

## Authentication

All endpoints are public and do not require authentication.

## Numeric Encoding

Many numeric fields are returned as **strings** to preserve precision:

* **Prices** (e.g. `open_24h`, `current_price`) — human-readable decimal strings, e.g. `"65498.93658727"`.
* **USD amounts and factors** (e.g. `oi_long`, `volume_24h`, `*_usd`, `*_factor`) — fixed-point integers scaled by **1e30** (so `1e30` = `1.0`, and `750000...e30` = a `0.75` factor).
* **Token amounts** (e.g. `size_in_tokens`, `collateral_delta_amount`) — integers scaled by the token's own decimals.

## Response Format

Responses share a common envelope. Note that `is_success` is present only on the Kline endpoint:

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

## Supported Trading Pairs

Pairs are dynamic and returned by the Market List endpoint (`symbol` field). The testnet currently lists crypto majors (e.g. `BTC/USD`, `ETH/USD`, `BNB/USD`) and a rotating set of meme and long-tail markets (e.g. `DOGE/USD`, `MOODENG/USD`, `0G/USD`). Query `GET /api/v1/bsc/markets` for the live list.

## Common Parameters

| Parameter      | Type   | Description                                          |
| -------------- | ------ | ---------------------------------------------------- |
| `symbol`       | string | Trading pair symbol (e.g. `ETH/USD`)                 |
| `interval`     | string | Kline interval (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`) |
| `limit`        | number | Number of results to return                          |
| `user_address` | string | Wallet address, 42 chars (`0x` + 40 hex)             |
| `cursor`       | string | Pagination cursor (empty string for first page)      |

## Error Handling

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

## Quick Start

#### Get all markets

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

#### Get latest ETH price

```bash
curl "https://data-statistics-query.beatnet.htzfl.link/api/v1/bsc/prices/24h" \
  | jq '.data.prices[] | select(.symbol == "ETH/USD")'
```

#### Get ETH Klines (15m)

```bash
curl "https://kline-query.testnet.htzfl.link/api/v1/historyKLines?symbol=ETH/USD&interval=15m&limit=10"
```


---

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

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

The question should be specific, self-contained, and written in natural language.
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.