> ## 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-zh-TW.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.