BlockVectra Stocks API

openapi: 3.2.0
info:
  title: BlockVectra Data Stocks API
  version: 0.1.3
  description: BlockVectra Data API — read-only REST endpoints over indexed data for each supported chain. The base URL is `https://api.blockvectra.com/v1/data`; supply your API key in the `x-api-key` header.
  contact:
    name: BlockVectra
servers:
- url: https://api.blockvectra.com/v1/data
  description: BlockVectra Data API
security:
- ApiKeyHeader: []
tags:
- name: Stocks
  description: Tokenized-stock daily activity.
paths:
  /{chain}/stocks:
    get:
      tags:
      - Stocks
      summary: Daily leaderboard of tokenized stocks
      description: 'Daily leaderboard of tokenized stock activity for a specified UTC date, including display metadata (symbol, name) ordered by transfer activity descending. Not paginated (`limit` caps the page).

        **Snapshot freshness**: the leaderboard comes from a daily table that the data store refreshes once a day, so the latest day can be missing or partial for up to about a day. `as_of_block` here is the service''s current indexed head, not the block height of the snapshot; read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`.'
      operationId: getStocks
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - name: day
        in: query
        required: false
        description: 'UTC day, `YYYY-MM-DD`. Absent defaults to the latest recorded day (if no activity is recorded, returns `200` with `data: []`).'
        schema:
          type: string
          format: date
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Stock tokens active on `day`, most active first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockDailyListEnvelope'
        '400':
          description: '`error.code = "bad_request"`: `day` present but not a valid `YYYY-MM-DD` calendar date, or invalid `limit`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/NotIndexedYetEmptyChain'
        '422':
          $ref: '#/components/responses/NoCoverage'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /{chain}/stocks/{token}:
    get:
      tags:
      - Stocks
      summary: Get one tokenized stock
      description: 'Fetch tokenized stock metadata and up to 30 days of recent daily metrics by token address.

        **Snapshot freshness**: the daily metrics come from a table that the data store refreshes once a day, so the latest day can be missing or partial for up to about a day. `as_of_block` here is the service''s current indexed head, not the block height of the snapshot; read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`.'
      operationId: getStockByToken
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - $ref: '#/components/parameters/TokenPath'
      responses:
        '200':
          description: This stock token's metadata plus its recent daily metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockTokenEnvelope'
        '400':
          description: '`error.code = "bad_request"`: invalid `{token}`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          description: '`error.code = "not_found"`: either `{chain}` is unknown or not public, or `{token}` is not a known tokenized stock.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          $ref: '#/components/responses/NotIndexedYetEmptyChain'
        '422':
          $ref: '#/components/responses/NoCoverage'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    StockDailyListEnvelope:
      type: object
      required:
      - data
      - meta
      description: '`next_cursor` is never present (this endpoint has no pagination).'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/StockDaily'
        meta:
          $ref: '#/components/schemas/Meta'
    AddressInput:
      type: string
      description: 20-byte address. `0x`/`0X` prefix optional; either hex digit case is accepted.
      pattern: ^(0[xX])?[0-9a-fA-F]{40}$
      example: '0xAbCdEf0123456789aBcDeF0123456789aBCDEF01'
    StockTokenEnvelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/StockToken'
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      description: Metadata present on every success response.
      required:
      - chain
      - chain_slug
      - chain_external_id
      - as_of_block
      - safe_block
      - finalized_block
      - coverage
      - refreshed_at
      properties:
        chain:
          type: string
          description: Chain identifier; the value of the `{chain}` path parameter.
          example: robinhood_mainnet
        chain_slug:
          type: string
          description: Canonical uppercase chain slug; `chain` is always its lowercase form.
          example: ROBINHOOD_MAINNET
        chain_external_id:
          type: string
          description: CAIP-2 formatted external chain identifier (`eip155:{chain_id}`).
          example: eip155:4663
        as_of_block:
          type: integer
          format: int64
          description: 'The newest fully written block (the `blocks` table''s maximum height); the only serving bound for block-scoped endpoints. For snapshot endpoints (balances, holders, nfts, dex prices, stocks) it is the service''s current indexed head, not the block height of the snapshot: read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`.'
        safe_block:
          type:
          - integer
          - 'null'
          format: int64
          description: 'A marker only: the node''s consensus `safe` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, never below `finalized_block`, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description.'
        finalized_block:
          type:
          - integer
          - 'null'
          format: int64
          description: 'A marker only: the node''s consensus `finalized` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description.'
        coverage:
          type: string
          enum:
          - full
          - partial
          description: '`"partial"` appears only from `GET /{chain}/addresses/{address}/transactions` and `GET /{chain}/addresses/{address}/transfers`, when `clamp=true` narrowed the served window, and from those two, `GET /{chain}/tokens/{token}/transfers` and `GET /{chain}/dex/swaps` when the block window starts before the lower bound of the dataset the endpoint reads -- the chain''s first indexed block, or higher while that dataset is still being backfilled (see Coverage in the API description and each endpoint''s window description). Every other endpoint reports `"full"`.'
        refreshed_at:
          description: 'When the data behind this response was last updated (UTC): the timestamp of `as_of_block` for block-based endpoints, the latest snapshot time for snapshot endpoints, and the last update time for token metadata and status. `null` means the snapshot''s update time is currently unknown: treat the data as stale; it never means "just refreshed".'
          oneOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
    ErrorBody:
      type: object
      description: The only shape any non-2xx response ever takes. `code` and `message` are always present; `indexed_through` is present only on `error.code = "not_indexed_yet"` on a chain with an indexed block, and absent (never `null`) otherwise. No other field is ever added.
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - code
          - message
          additionalProperties: false
          properties:
            code:
              type: string
              description: Stable machine-readable identifier; see each operation for the exact set of values it can return.
            message:
              type: string
              description: Free-form English text for logs/debugging. Do not pattern-match on it.
            indexed_through:
              type: integer
              format: int64
              description: 'Highest indexed block on this chain. Present only when `code = "not_indexed_yet"` and the chain has at least one indexed block; absent when it has none at all (an absent value is not `0`: block 0 indexed is `indexed_through: 0`).'
            data:
              type: object
              description: Optional structured error details.
              additionalProperties: true
    StockToken:
      type: object
      required:
      - address
      - symbol
      - name
      - decimals
      - created_block
      - created_tx_hash
      - factory
      - creator
      - mint_address
      - burn_address
      - refreshed_at
      - daily
      properties:
        address:
          $ref: '#/components/schemas/Address'
        symbol:
          type: string
        name:
          type: string
        decimals:
          oneOf:
          - type: integer
            minimum: 0
            maximum: 255
          - type: 'null'
        created_block:
          type: integer
          format: int64
        created_tx_hash:
          $ref: '#/components/schemas/Hash32'
        factory:
          $ref: '#/components/schemas/Address'
        creator:
          oneOf:
          - $ref: '#/components/schemas/Address'
          - type: 'null'
        mint_address:
          oneOf:
          - $ref: '#/components/schemas/Address'
          - type: 'null'
        burn_address:
          oneOf:
          - $ref: '#/components/schemas/Address'
          - type: 'null'
        refreshed_at:
          $ref: '#/components/schemas/Timestamp'
        daily:
          type: array
          description: Most recent 30 days of daily metrics, newest first.
          items:
            $ref: '#/components/schemas/StockDailyMetric'
          maxItems: 30
    Timestamp:
      type: string
      format: date-time
      description: '`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision.'
      example: 2026-09-26 05:41:07+00:00
    Address:
      type: string
      description: 20-byte address, canonical form always `0x` + 40 lowercase hex digits.
      pattern: ^0x[0-9a-f]{40}$
    DateOnly:
      type: string
      format: date
      description: '`YYYY-MM-DD`, UTC calendar day.'
      example: 2026-09-26
    StockDaily:
      type: object
      required:
      - day
      - token
      - symbol
      - name
      - transfers
      - unique_senders
      - unique_receivers
      - mint_raw_amount
      - burn_raw_amount
      - net_supply_change
      - holder_count
      - top10_holder_share_bps
      - dex_swap_count
      - dex_raw_volume
      - refreshed_at
      properties:
        day:
          $ref: '#/components/schemas/DateOnly'
        token:
          $ref: '#/components/schemas/Address'
        symbol:
          type: string
        name:
          type: string
          description: Empty string when no matching name metadata is available.
        transfers:
          type: integer
          format: int64
        unique_senders:
          type: integer
          format: int64
        unique_receivers:
          type: integer
          format: int64
        mint_raw_amount:
          $ref: '#/components/schemas/UInt256String'
        burn_raw_amount:
          $ref: '#/components/schemas/UInt256String'
        net_supply_change:
          $ref: '#/components/schemas/Int256String'
        holder_count:
          type: integer
          format: int64
        top10_holder_share_bps:
          type: integer
          description: Basis points (0-10000).
        dex_swap_count:
          type: integer
          format: int64
        dex_raw_volume:
          $ref: '#/components/schemas/UInt256String'
        refreshed_at:
          $ref: '#/components/schemas/Timestamp'
    Hash32:
      type: string
      description: 32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.
      pattern: ^0x[0-9a-f]{64}$
    Int256String:
      type: string
      description: Signed integer that may exceed +-2^53, rendered as a plain decimal string, optionally sign-prefixed.
      pattern: ^-?[0-9]+$
    UInt256String:
      type: string
      description: Non-negative integer that may exceed 2^53, rendered as a plain decimal string — never a JSON number, never scientific or hex notation.
      pattern: ^[0-9]+$
      example: '9007199254740993'
    StockDailyMetric:
      type: object
      required:
      - day
      - transfers
      - unique_senders
      - unique_receivers
      - mint_raw_amount
      - burn_raw_amount
      - net_supply_change
      - holder_count
      - top10_holder_share_bps
      - dex_swap_count
      - dex_raw_volume
      - refreshed_at
      properties:
        day:
          $ref: '#/components/schemas/DateOnly'
        transfers:
          type: integer
          format: int64
        unique_senders:
          type: integer
          format: int64
        unique_receivers:
          type: integer
          format: int64
        mint_raw_amount:
          $ref: '#/components/schemas/UInt256String'
        burn_raw_amount:
          $ref: '#/components/schemas/UInt256String'
        net_supply_change:
          $ref: '#/components/schemas/Int256String'
        holder_count:
          type: integer
          format: int64
        top10_holder_share_bps:
          type: integer
        dex_swap_count:
          type: integer
          format: int64
        dex_raw_volume:
          $ref: '#/components/schemas/UInt256String'
        refreshed_at:
          $ref: '#/components/schemas/Timestamp'
  responses:
    GatewayPaymentRequired:
      description: 'Payment required: the paid balance or the free grant is exhausted. The response body is `{"error":{"code":"insufficient_balance"}}`. Rejected requests are not billed.'
    Unavailable:
      description: '`error.code = "unavailable"`: the service is temporarily unavailable, timed out, busy on this chain (no query slot freed up in time, see `limits.max_concurrent_queries` in `GET /chains`), or shutting down (see "Errors" above). Always carries an HTTP `Retry-After` header (seconds); wait at least that long before retrying.'
      headers:
        Retry-After:
          required: true
          schema:
            type: integer
            minimum: 1
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error:
              code: unavailable
              message: service temporarily unavailable, please retry
    GatewayRateLimited:
      description: Rate limited. `{"error":{"code":"rate_limited"}}` when the key CU rate limit is exceeded (the response includes `Retry-After`) or the account call rate limit is exceeded (no `Retry-After`). `{"error":{"code":"cost_exceeds_burst"}}` when a single request exceeds the key burst capacity; split the request, retrying as sent never succeeds. Rejected requests are not billed.
    NotFound:
      description: '`error.code = "not_found"`: the target object was not found, or `{chain}` is not a registered or public chain (returns HTTP 404 with `error.code = "not_found"`, not billed).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            unknown_chain:
              summary: Unknown or not-public chain
              value:
                error:
                  code: not_found
                  message: unknown chain
            object_not_found:
              summary: Resource not found
              value:
                error:
                  code: not_found
                  message: block not found
          example:
            error:
              code: not_found
              message: unknown chain
    NoCoverage:
      description: '`error.code = "no_coverage"`: no data here, which is permanent except while a dataset is being backfilled (a windowed endpoint''s lower bound can move down as the backfill proceeds, so retry later). Either the chain does not have this endpoint''s capability, or the requested block (or whole block window) is before the chain''s first covered block (`coverage.from_block`) -- for the windowed endpoints, the lower bound of the dataset they read, which is that block or higher while the dataset is still being backfilled -- or the capability needs history from genesis (`balances`, `holders`, `nfts`) and `coverage.from_block` is not `0` yet or the indexed blocks have holes, or (traces) the block falls in a permanent trace coverage gap. A block window entirely before the lower bound is reported as this `422` even when its `to_block` is also above `as_of_block`. See Coverage in the API description (the history start in examples is a placeholder; read `GET /chains` `coverage.from_block` at runtime).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            capability:
              value:
                error:
                  code: no_coverage
                  message: chain 'eth_mainnet' does not support balances
            before_history:
              summary: the start is live -- read `GET /chains` `coverage.from_block` at runtime
              value:
                error:
                  code: no_coverage
                  message: block 1 is before indexed history start <from_block> on chain 'eth_mainnet'
            history_not_at_genesis:
              summary: balances, holders and nfts need history from genesis
              value:
                error:
                  code: no_coverage
                  message: 'chain ''eth_mainnet'' does not serve balances yet: it needs history from genesis and indexed history starts at block <from_block>'
    GatewayUnauthorized:
      description: 'HTTP 401: a missing API key returns missing_api_key; an unknown, disabled, or revoked key returns the same invalid_api_key error envelope. error.code and error.data.reason contain the reason. Rejected requests are not billed.'
      content:
        application/json:
          examples:
            missing_api_key:
              value:
                error:
                  code: missing_api_key
                  message: 'missing API key: send it in the x-api-key header'
                  data:
                    reason: missing_api_key
                    docs_url: https://docs.blockvectra.com/en/errors/#missing_api_key
                    retryable: false
            invalid_api_key:
              value:
                error:
                  code: invalid_api_key
                  message: 'invalid API key: it is unknown, disabled or revoked; check the key in the console'
                  data:
                    reason: invalid_api_key
                    docs_url: https://docs.blockvectra.com/en/errors/#invalid_api_key
                    retryable: false
    NotIndexedYetEmptyChain:
      description: 'After the operation passes its earlier routing, capability, parameter and permit checks and reaches the indexed-head check, `error.code = "not_indexed_yet"` without `indexed_through`: the chain has no indexed block at all yet (`GET /chains` `coverage.has_data = false`), so there is no head to answer against (see "Errors" above). Transient: retry later. A missing capability (including `traces`) is checked before the empty head and returns `422 no_coverage` instead.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error:
              code: not_indexed_yet
              message: 'chain ''hyperevm_mainnet'' has no indexed data yet: no block has been indexed'
  parameters:
    TokenPath:
      name: token
      in: path
      required: true
      description: 20-byte token contract address, `0x` optional, either case.
      schema:
        $ref: '#/components/schemas/AddressInput'
    ChainParam:
      name: chain
      in: path
      required: true
      description: 'Chain identifier: the `chain` value of an entry in `GET /chains` (for example `robinhood_mainnet`), which lists every value this API accepts, i.e. the exact lowercase form of that entry''s `chain_slug`. Matching is exact and case-sensitive; other spellings, aliases and numeric chain IDs are not accepted and return `404 not_found` (unknown or not-public chain). What the chain serves differs per chain: see that entry''s `features` and `coverage`.'
      schema:
        type: string
        pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)+$
      examples:
        robinhood_mainnet:
          value: robinhood_mainnet
        eth_mainnet:
          value: eth_mainnet
    Limit:
      name: limit
      in: query
      required: false
      description: Page size. Absent defaults to 50. `0` or a non-integer value is `400 bad_request`. A value above 500 is clamped to 500, not rejected.
      schema:
        type: integer
        minimum: 1
        default: 50
        maximum: 500
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your BlockVectra API key.