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

# OHLCV candles at one timeframe for each named token, oldest first.

> `tokens` names 1 to 10 addresses, and each costs one credit. A token reads on every chain in
scope of its address family. Each chain where it has candles in the window answers one
series, and a token with none answers no series.
`countBack` asks for a bar count and supersedes `from`. `to` and `timeframe` still apply. A
page holds the newest candles of the window: `countBack` of them, else 5000 after `from`, else
500. `cursor` reads a series' older candles.



## OpenAPI

````yaml /specs/openapi.json get /v1/ohlcv
openapi: 3.1.0
info:
  title: Metastreams API
  description: >-
    The Metastreams market-data API. Amounts are decimal strings, timestamps are
    Unix milliseconds, and every field name is camelCase.
  license:
    name: Proprietary
  version: 1.0.0
servers:
  - url: https://{host}
    variables:
      host:
        default: api.metastreams.io
        description: API host.
security:
  - bearerKey: []
paths:
  /v1/ohlcv:
    get:
      tags:
        - ohlcv
      summary: OHLCV candles at one timeframe for each named token, oldest first.
      description: >-
        `tokens` names 1 to 10 addresses, and each costs one credit. A token
        reads on every chain in

        scope of its address family. Each chain where it has candles in the
        window answers one

        series, and a token with none answers no series.

        `countBack` asks for a bar count and supersedes `from`. `to` and
        `timeframe` still apply. A

        page holds the newest candles of the window: `countBack` of them, else
        5000 after `from`, else

        500. `cursor` reads a series' older candles.
      operationId: candle_series
      parameters:
        - name: tokens
          in: query
          description: >-
            Token addresses, CSV; one to 10. Each reads on every chain in scope
            of its address family.
          required: true
          schema:
            type: string
          example: So11111111111111111111111111111111111111112
        - name: chains
          in: query
          description: >-
            Chains to scope to, CSV of the chain slugs. Absent means every spot
            chain.
          required: false
          schema:
            type: string
          example: solana,bsc
        - name: pool
          in: query
          description: >-
            Pool address. When present, the read takes this pool's candles, and
            `tokens` names its

            token alone. When absent, each token reads across all of its pools.
          required: false
          schema:
            type: string
          example: 58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2
        - name: timeframe
          in: query
          description: Candle bucket size; defaults to `1m`.
          required: false
          schema:
            type: string
            description: Candle bucket size; defaults to `1m`.
            default: 1m
            enum:
              - 1s
              - 5s
              - 15s
              - 30s
              - 1m
              - 3m
              - 5m
              - 15m
              - 30m
              - 1h
              - 4h
              - 6h
              - 12h
              - 1d
              - 7d
        - name: metric
          in: query
          description: OHLC metric, `price` or `marketCap`; defaults to `marketCap`.
          required: false
          schema:
            type: string
            default: marketCap
        - name: denomination
          in: query
          description: OHLC denomination; defaults to `usd`.
          required: false
          schema:
            type: string
            default: usd
        - name: from
          in: query
          description: >-
            Window start, inclusive; ignored when `countBack` is set. A window
            holding

            more candles than the cap keeps the newest.
          required: false
          schema:
            $ref: '#/components/schemas/UnixMilliseconds'
        - name: to
          in: query
          description: Window end, exclusive.
          required: false
          schema:
            $ref: '#/components/schemas/UnixMilliseconds'
        - name: countBack
          in: query
          description: >-
            `TradingView` bar count per series: the most recent N buckets at or
            before `to`.

            Takes priority over `from`.
          required: false
          schema:
            type: integer
            format: int32
            maximum: 5000
            minimum: 1
        - name: cursor
          in: query
          description: >-
            A series' `nextCursor`, to read its next, older page. The request
            names that series' token

            in `tokens`, and its chain in `chains` when the token's address
            family spans several.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: >-
            One series per chain where each named token, or its `pool`, has
            candles in the window, in the order the request named them. Each
            holds one page of candles, one per bucket that traded, oldest first.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UiCandleSeries'
        '400':
          description: >-
            Unsupported chain, a malformed token address, a token count outside
            1-10, a `pool` beside more than one token, a `pool` of another
            address format than its token, a `pool` at the zero address, an
            unknown timeframe, an inverted range, a `countBack` outside 1-5000,
            a cursor sent with other tokens or chains than its own series, a
            cursor under other options, or a malformed parameter.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: >-
            Missing or invalid credential: an API key, or a session token a key
            minted.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: >-
            The organization's credits this billing period reach its plan's
            limit.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            A key whose plan excludes this endpoint gets `FORBIDDEN`. A session
            token from an

            origin it does not name gets `ORIGIN_NOT_ALLOWED`.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Unexpected server failure.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Dependency down or maintenance.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    UnixMilliseconds:
      type: integer
      format: int64
      description: An instant, as milliseconds since the Unix epoch.
    UiCandleSeries:
      type: object
      description: >-
        One token's candle buckets on one chain, an element of the `GET
        /v1/ohlcv` response.
      required:
        - chain
        - address
        - candles
        - hasMore
      properties:
        address:
          type: string
          description: Token address.
        candles:
          type: array
          items:
            $ref: '#/components/schemas/UiCandle'
          description: Buckets on this page, oldest first.
        chain:
          $ref: '#/components/schemas/SpotChain'
          description: Chain the token trades on.
        hasMore:
          type: boolean
          description: Whether this series has older candles in the window.
        nextCursor:
          type:
            - string
            - 'null'
          description: >-
            The cursor of this series' next, older page when `hasMore` is
            `true`; `null` on its last

            page.
    ErrorEnvelope:
      type: object
      description: The complete error response body — every error is exactly this.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: The error.
    UiCandle:
      type: object
      description: >-
        One chart OHLC bucket. The request's metric decides whether the values
        are

        prices or market caps, and its denomination decides what they are
        denominated in.


        Values are JSON numbers, the one amount on this surface that is: a chart

        client consumes them as floats, and every OHLCV feed it already reads is

        shaped this way. A bucket with no trades in it is not emitted, so a
        series

        is sparse.
      required:
        - time
        - open
        - high
        - low
        - close
        - volume
      properties:
        close:
          type: number
          format: double
          description: Closing value.
          example: 0.7
        high:
          type: number
          format: double
          description: Highest value.
          example: 2
        low:
          type: number
          format: double
          description: Lowest value.
          example: 0.5
        open:
          type: number
          format: double
          description: Opening value.
          example: 1
        time:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: Candle open time.
        volume:
          type: number
          format: double
          description: Traded volume, in the requested denomination.
          example: 1000
    SpotChain:
      type: string
      description: >-
        Chain slug. One spelling per chain, in paths and bodies alike. Only a
        chain with spot data is published.
      enum:
        - solana
        - bsc
        - robinhood
        - elysium
        - ethereum
    ErrorDetail:
      type: object
      description: The `error` object inside the envelope.
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: >-
            Stable, machine-readable. Clients switch on this, never on
            `message`.
        details:
          description: Optional; shape is fixed per code.
        message:
          type: string
          description: |-
            Human-readable, written for the integrating developer:
            `[What happened]. [What to do next — if actionable].`
    ErrorCode:
      type: string
      description: |-
        Every wire error code the API can return.

        Append-only: a new code is non-breaking, since clients fall back on the
        HTTP status for one they do not recognize, and a published code is never
        renamed or removed.
      enum:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION_ERROR
        - UNSUPPORTED_CHAIN
        - NOT_FOUND
        - RATE_LIMITED
        - CREDITS_EXHAUSTED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - RANGE_TOO_LARGE
        - INVALID_CREDENTIALS
        - ORIGIN_NOT_ALLOWED
        - NOT_ORG_MEMBER
        - MEMBERSHIP_INACTIVE
        - EMAIL_NOT_VERIFIED
        - EMAIL_TAKEN
        - ALREADY_MEMBER
        - INVITATION_ALREADY_SENT
        - INVITATION_ALREADY_ACCEPTED
        - LAST_ADMIN
        - CANNOT_REMOVE_SELF
        - KEY_LIMIT_REACHED
        - TOKEN_EXPIRED
        - PAYLOAD_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - IMAGE_TOO_LARGE
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: >-
        Send an API key, or a session token a key minted, as `Authorization:
        Bearer <credential>`. A browser opening `/v1/stream` offers its session
        token in `Sec-WebSocket-Protocol` instead.

````

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