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

# Get Crypto Candlesticks

> Query public OHLCV candlesticks by currency code, including request parameters, time units, and response fields.

Use a currency code to query public OHLCV candlesticks. Authentication is not required.

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

## Request parameters

| Parameter | Required | Description |
| - | - | - |
| `symbol` | One of two | Case-insensitive currency code. Currently supported: `BTC`, `ETH`, `HYPE`, `XRP`, `SOL`, `DOGE`, and `BNB`. Use this parameter for new integrations. |
| `tag_id` | One of two | Compatibility parameter: positive cryptocurrency tag ID; for example, BTC is `235`. Do not add the `ge_` prefix. |
| `interval` | Yes | Display interval: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`, `1mon`, `1y`, or `all`. |
| `start_ts` | No | Start time in Unix seconds; omit or pass `0` to use the server's default boundary rule. |
| `end_ts` | No | End time in Unix seconds; omit or pass `0` to use the server's default boundary rule. |

Provide exactly one of `symbol` or `tag_id`. The `tag_id` parameter remains temporarily supported; existing integrations should migrate to `symbol`. When both boundaries are nonzero, `end_ts` must be greater than `start_ts`.

`interval` selects a display interval and does not guarantee the width of each returned candlestick. Use `history[].t` to read sample times. `interval=all` does not guarantee the full price history; specify `start_ts` and `end_ts` to query a particular range.

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

## Response

A successful response contains the currency pair, display interval, and candlestick history:

```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` is a Unix timestamp in seconds. Open, high, low, close, and volume are decimal strings. `source` is a data source name and is omitted when unavailable. Sources without volume may return `"0"`; no data returns an empty `history` array.

Invalid parameters return HTTP 400 with `label` set to `INVALID_PARAM_VALUE`. An unavailable quote source returns HTTP 503 with `label` set to `QUOTE_UNAVAILABLE`.


## OpenAPI

````yaml openapi/event-contracts-en.yaml GET /api/v4/event_contracts/crypto/candlesticks
openapi: 3.0.3
info:
  title: DexBuilder Event Contracts API
  version: 1.0.0
  description: DexBuilder Event Contracts REST API.
servers:
  - url: https://api.dexbuilder.com
security: []
paths:
  /api/v4/event_contracts/crypto/candlesticks:
    get:
      summary: Get Crypto Candlesticks
      description: >-
        Query OHLCV candlesticks using the `symbol` currency code. The `tag_id`
        parameter remains temporarily supported. Provide exactly one of `symbol`
        or `tag_id`. `interval=all` does not guarantee the full price history;
        specify `start_ts` and `end_ts` to query a particular range.
      operationId: query_crypto_candlesticks
      parameters:
        - name: symbol
          in: query
          required: false
          description: >-
            Case-insensitive currency code. Currently supported: BTC, ETH, HYPE,
            XRP, SOL, DOGE, and BNB. Provide either `symbol` or `tag_id`.
          schema:
            type: string
            example: BTC
        - name: tag_id
          in: query
          required: false
          description: >-
            Compatibility parameter: positive cryptocurrency tag ID. Provide
            either `symbol` or `tag_id`. Use `symbol` for new integrations.
          schema:
            type: integer
            minimum: 1
            example: 235
          deprecated: true
        - name: interval
          in: query
          required: true
          description: Display interval.
          schema:
            type: string
            enum:
              - 1m
              - 5m
              - 15m
              - 1h
              - 4h
              - 1d
              - 1w
              - 1mon
              - 1y
              - all
        - name: start_ts
          in: query
          required: false
          description: >-
            Start time in Unix seconds; omitted or 0 follows the server's
            default rule.
          schema:
            type: integer
            minimum: 0
        - name: end_ts
          in: query
          required: false
          description: >-
            End time in Unix seconds; omitted or 0 follows the server's default
            rule.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Request succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CryptoCandlesticksResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                label: INVALID_PARAM_VALUE
                message: invalid crypto candlestick parameters
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                label: QUOTE_UNAVAILABLE
                message: crypto candlesticks unavailable
components:
  schemas:
    CryptoCandlesticksResponse:
      type: object
      description: Crypto candlestick response.
      required:
        - symbol
        - interval
        - history
      properties:
        symbol:
          type: string
          description: Currency pair identifier.
        interval:
          type: string
        source:
          type: string
          description: Data source name; omitted when unavailable.
        history:
          type: array
          description: OHLCV candlesticks in time order.
          items:
            $ref: '#/components/schemas/CryptoCandlestick'
    Error:
      type: object
      description: Error response.
      properties:
        label:
          type: string
          example: INVALID_ARGUMENT
        message:
          type: string
          example: invalid request
    CryptoCandlestick:
      type: object
      description: One candlestick.
      required:
        - t
        - o
        - h
        - l
        - c
        - v
      properties:
        t:
          type: integer
          description: Unix timestamp in seconds.
        o:
          type: string
        h:
          type: string
        l:
          type: string
        c:
          type: string
        v:
          type: string
          description: Volume as a decimal string; sources without volume may return 0.

````

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