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

# Get candles

> Get historical OHLCV candles for a market over a time range.

`interval` and `from` are required; `from` and `to` are Unix timestamps in milliseconds and `to` defaults to the current interval boundary. A request returns at most 5000 candles: when the range is wider, the most recent 5000 before `to` are returned. To read a longer history, request windows of at most 5000 intervals and move both `from` and `to`. Prices and `volume` are decimal strings; `volume` is in base asset units. This is a plain GET; the Perps API has no streaming price feed.


## OpenAPI

````yaml openapi-perps.json GET /v1/markets/{marketId}/candles
openapi: 3.0.0
info:
  title: 'Yield API: Trade (Perps)'
  description: >-
    API Documentation. Errors follow a uniform envelope with `details.code` from
    the public catalog (https://docs.yield.xyz). ValidationPipe failures use
    `validation.message: string[]`.
  version: '1.0'
  contact: {}
servers:
  - url: https://perps.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover perps markets, networks, and providers
  - name: Portfolio
    description: User-specific positions, orders, and balances
  - name: Actions
    description: Generate transactions to open, close, and manage positions
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/markets/{marketId}/candles:
    get:
      tags:
        - Markets
        - Market Data
      summary: Get historical candles
      description: >-
        Retrieve historical OHLCV candle data for a market. Limited to 5000
        candles per request.
      operationId: MarketsController_getCandles_v1
      parameters:
        - name: marketId
          required: true
          in: path
          description: The market identifier
          schema:
            type: string
            example: hyperliquid-btc-usdc
        - name: interval
          required: true
          in: query
          schema:
            type: string
            enum:
              - 1m
              - 5m
              - 15m
              - 1h
              - 4h
              - 1d
            example: 1h
        - name: from
          required: true
          in: query
          description: Start time (unix milliseconds)
          schema:
            example: 1704067200000
            type: number
        - name: to
          required: false
          in: query
          description: End time (unix milliseconds)
          schema:
            example: 1704153600000
            type: number
      responses:
        '200':
          description: Candle data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandlesResponseDto'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 401
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Invalid API key
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Invalid API key
                      code:
                        type: string
                        example: AUTH_INVALID_API_KEY
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 429
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Rate limit exceeded
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Rate limit exceeded
                      code:
                        type: string
                        example: RATE_LIMIT_EXCEEDED
                      error:
                        type: string
                        example: Too Many Requests
                      retryAfter:
                        type: number
                        example: 30
      security:
        - ApiKey: []
components:
  schemas:
    CandlesResponseDto:
      type: object
      properties:
        marketId:
          type: string
          example: hyperliquid-btc-usdc
        interval:
          type: string
          enum:
            - 1m
            - 5m
            - 15m
            - 1h
            - 4h
            - 1d
          example: 1h
        candles:
          type: array
          items:
            $ref: '#/components/schemas/CandleDto'
      required:
        - marketId
        - interval
        - candles
    CandleDto:
      type: object
      properties:
        openTime:
          type: number
          description: Candle open time (unix milliseconds)
          example: 1704067200000
        closeTime:
          type: number
          description: Candle close time (unix milliseconds)
          example: 1704070799999
        open:
          type: string
          example: '42150.5'
        high:
          type: string
          example: '42500.0'
        low:
          type: string
          example: '42000.0'
        close:
          type: string
          example: '42350.25'
        volume:
          type: string
          description: Volume in base asset units
          example: '1234.56'
        trades:
          type: number
          description: Number of trades in this candle
          example: 482
      required:
        - openTime
        - closeTime
        - open
        - high
        - low
        - close
        - volume
        - trades
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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