> ## Documentation Index
> Fetch the complete documentation index at: https://dexbuilder.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询加密货币 K 线

> 按币种代码查询公开 OHLCV K 线，了解请求参数、时间单位和响应字段。

通过币种代码查询公开 OHLCV K 线。此接口无需认证。

Base URL：`https://api.dexbuilder.com`

## 请求参数

| 参数 | 必填 | 说明 |
| - | - | - |
| `symbol` | 二选一 | 币种代码，不区分大小写。当前支持 `BTC`、`ETH`、`HYPE`、`XRP`、`SOL`、`DOGE`、`BNB`；新接入建议使用此参数。 |
| `tag_id` | 二选一 | 兼容参数：正整数加密货币标签 ID，例如 BTC 为 `235`；不接受 `ge_` 前缀。 |
| `interval` | 是 | 展示档位：`1m`、`5m`、`15m`、`1h`、`4h`、`1d`、`1w`、`1mon`、`1y`、`all`。 |
| `start_ts` | 否 | 起始 Unix 秒；省略或传 `0` 时按服务端默认规则处理。 |
| `end_ts` | 否 | 结束 Unix 秒；省略或传 `0` 时按服务端默认规则处理。 |

`symbol` 与 `tag_id` 必须且只能提供其中一个。`tag_id` 暂时保留兼容，建议已有调用迁移到 `symbol`。两个非零时间边界同时提供时，`end_ts` 必须大于 `start_ts`。

`interval` 选择展示档位，不保证每根返回 K 线的时间宽度；请使用 `history[].t` 判断采样时间。`interval=all` 不保证返回全部历史；查询指定范围时请传入 `start_ts` 和 `end_ts`。

```bash theme={null}
curl "https://api.dexbuilder.com/api/v4/prediction/crypto/candlesticks?symbol=BTC&interval=1h"
```

## 响应

成功时返回包含币种交易对、展示档位及历史 K 线的对象：

```json theme={null}
{
  "symbol": "BTCUSD",
  "interval": "1h",
  "source": "binance",
  "history": [
    { "t": 1700000000, "o": "30000", "h": "30100", "l": "29900", "c": "30050", "v": "12.5" }
  ]
}
```

`history[].t` 为 Unix 秒；开、高、低、收和成交量均为十进制字符串。`source` 为数据源名称，未提供时该字段省略。某些数据源没有成交量，可返回 `"0"`；无数据时 `history` 为 `[]`。

参数无效返回 HTTP 400，错误 `label` 为 `INVALID_PARAM_VALUE`；行情源不可用返回 HTTP 503，错误 `label` 为 `QUOTE_UNAVAILABLE`。


## OpenAPI

````yaml openapi/event-markets.yaml GET /api/v4/prediction/crypto/candlesticks
openapi: 3.0.3
info:
  title: DexBuilder Prediction Market API
  version: 1.0.0
  description: DexBuilder 事件市场 REST API
servers:
  - url: https://api.dexbuilder.com
security: []
paths:
  /api/v4/prediction/crypto/candlesticks:
    get:
      summary: 查询加密货币 K 线
      description: >-
        使用币种代码 `symbol` 查询 OHLCV K 线；暂时兼容 `tag_id`。两者必须且只能提供一个。`interval=all`
        不保证返回全部历史；查询指定范围时请提供 `start_ts` 和 `end_ts`。
      operationId: query_crypto_candlesticks
      parameters:
        - name: symbol
          in: query
          required: false
          description: 币种代码，大小写不敏感。当前支持 BTC、ETH、HYPE、XRP、SOL、DOGE、BNB；与 `tag_id` 二选一。
          schema:
            type: string
            example: BTC
        - name: tag_id
          in: query
          required: false
          description: 兼容参数：正整数加密货币标签 ID；与 `symbol` 二选一。新接入建议使用 `symbol`。
          schema:
            type: integer
            minimum: 1
            example: 235
          deprecated: true
        - name: interval
          in: query
          required: true
          description: 展示档位。
          schema:
            type: string
            enum:
              - 1m
              - 5m
              - 15m
              - 1h
              - 4h
              - 1d
              - 1w
              - 1mon
              - 1y
              - all
        - name: start_ts
          in: query
          required: false
          description: 起始 Unix 秒；省略或为 0 时按服务端默认规则处理。
          schema:
            type: integer
            minimum: 0
        - name: end_ts
          in: query
          required: false
          description: 结束 Unix 秒；省略或为 0 时按服务端默认规则处理。
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CryptoCandlesticksResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                label: INVALID_PARAM_VALUE
                message: invalid crypto candlestick parameters
        '503':
          description: 服务暂时不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                label: QUOTE_UNAVAILABLE
                message: crypto candlesticks unavailable
components:
  schemas:
    CryptoCandlesticksResponse:
      type: object
      description: 加密货币 K 线响应。
      required:
        - symbol
        - interval
        - history
      properties:
        symbol:
          type: string
          description: 币种交易对标识。
        interval:
          type: string
        source:
          type: string
          description: 数据源名称；上游未提供时省略。
        history:
          type: array
          description: OHLCV K 线，按时间返回。
          items:
            $ref: '#/components/schemas/CryptoCandlestick'
    Error:
      type: object
      description: 错误响应。
      properties:
        label:
          type: string
          example: INVALID_ARGUMENT
        message:
          type: string
          example: invalid request
    CryptoCandlestick:
      type: object
      description: 单根 K 线。
      required:
        - t
        - o
        - h
        - l
        - c
        - v
      properties:
        t:
          type: integer
          description: Unix 秒时间戳。
        o:
          type: string
        h:
          type: string
        l:
          type: string
        c:
          type: string
        v:
          type: string
          description: 成交量字符串；无成交量的数据源可能返回 0。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.