BlockVectra Status API

openapi: 3.2.0
info:
  title: Blockvectra Status API
  version: '1.0'
  description: 'Operations tagged Status across 2 of this provider''s published API definitions: data.yaml, json-rpc.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.blockvectra.com/v1/data
  description: BlockVectra Data API
- url: https://api.blockvectra.com/v1
  description: BlockVectra JSON-RPC and Data API
tags:
- name: Status
  description: Data freshness for each public dataset.
paths:
  /{chain}/status/freshness:
    get:
      tags:
      - Status
      summary: Freshness and lag per dataset
      description: Latest indexed block/day for each public dataset and how far it lags the chain head. Values may be up to 5 s old. If the current answer is unavailable (`503`) but the previous successful answer is at most 60 s old, that answer is returned as `200` with `meta.stale = true` and `meta.stale_age_seconds` (how long ago it was queried); `checked_at` and `meta.refreshed_at` keep the real check time. Without such an answer it is `503`. A chain with no indexed block yet answers `409 not_indexed_yet` (no `indexed_through`) instead.
      operationId: getStatusFreshness
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      responses:
        '200':
          description: One row per tracked dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreshnessEnvelope'
              example:
                data:
                - dataset: blocks
                  category: raw
                  max_block_number: 2000000
                  max_day: null
                  max_time: 2026-09-28 03:41:07+00:00
                  seconds_behind: 0
                  blocks_behind: null
                  days_behind: null
                  checked_at: 2026-09-28 03:41:10+00:00
                - dataset: traces
                  category: raw
                  max_block_number: 2000000
                  max_day: null
                  max_time: 2026-09-28 03:41:07+00:00
                  seconds_behind: 0
                  blocks_behind: 0
                  days_behind: null
                  coverage_from_block: 1000000
                  coverage_to_block: 2000000
                  coverage_complete: true
                  checked_at: 2026-09-28 03:41:10+00:00
                - dataset: dex_prices
                  category: derived
                  max_block_number: null
                  max_day: 2026-09-27
                  max_time: 2026-09-27 00:00:00+00:00
                  seconds_behind: 99667
                  blocks_behind: null
                  days_behind: 1
                  checked_at: 2026-09-28 03:41:10+00:00
                meta:
                  chain: robinhood_mainnet
                  chain_slug: ROBINHOOD_MAINNET
                  chain_external_id: eip155:4663
                  as_of_block: 2000000
                  safe_block: 1999400
                  finalized_block: 1998900
                  coverage: full
                  refreshed_at: 2026-09-28 03:41:10+00:00
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: '`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 and no lag to report. Never a `200` with invented values.'
          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'
        '422':
          $ref: '#/components/responses/NoCoverage'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
      security:
      - ApiKeyHeader: []
    servers:
    - url: https://api.blockvectra.com/v1/data
      description: BlockVectra Data API
  /status:
    get:
      tags:
      - Status
      operationId: getStatus
      summary: Public service status
      description: '`GET /v1/status` returns the current status of the service for the public status page. No authentication, no billing, no rate limiting. Data is refreshed at most every 30 seconds.'
      security: []
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
    servers:
    - url: https://api.blockvectra.com/v1
      description: BlockVectra JSON-RPC and Data API
components:
  responses:
    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>'
    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.'
    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
    StatusOk:
      description: 'Current status of the service and the underlying chain. No authentication or billing; the response carries `Access-Control-Allow-Origin: *` and `Cache-Control: max-age=30`.'
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: '*'
        Cache-Control:
          description: How long clients and proxies may cache the response.
          schema:
            type: string
            example: max-age=30
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusResponseBody'
          examples:
            statusOk:
              $ref: '#/components/examples/statusOk'
  parameters:
    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
  schemas:
    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
    DateOnly:
      type: string
      format: date
      description: '`YYYY-MM-DD`, UTC calendar day.'
      example: 2026-09-26
    Timestamp:
      type: string
      format: date-time
      description: '`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision.'
      example: 2026-09-26 05:41:07+00:00
    FreshnessRow:
      type: object
      required:
      - dataset
      - category
      - max_block_number
      - max_day
      - max_time
      - seconds_behind
      - blocks_behind
      - days_behind
      - checked_at
      properties:
        dataset:
          type: string
          description: Public dataset identifier.
          enum:
          - blocks
          - transactions
          - logs
          - traces
          - erc20_transfers
          - erc721_transfers
          - erc1155_transfers
          - token_balances
          - erc1155_balances
          - tokens
          - nft_owners
          - dex_swaps
          - dex_prices
          - stocks
          - stock_daily
          example: blocks
        category:
          type: string
          enum:
          - raw
          - derived
          description: Dataset category classification (`raw` for core chain data, `derived` for computed datasets).
          example: raw
        max_block_number:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
        max_day:
          oneOf:
          - $ref: '#/components/schemas/DateOnly'
          - type: 'null'
        max_time:
          oneOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        seconds_behind:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
        blocks_behind:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
          description: Head of `blocks` minus `max_block_number`. Always `null` for `dataset = "blocks"` (it is the head itself; this is not the node lag).
        days_behind:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
        coverage_from_block:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
          description: Lowest block number indexed with traces. Present only when `dataset = "traces"`.
        coverage_to_block:
          oneOf:
          - type: integer
            format: int64
          - type: 'null'
          description: Highest block number indexed with traces. Present only when `dataset = "traces"`.
        coverage_complete:
          type: boolean
          description: Whether trace coverage between `coverage_from_block` and `coverage_to_block` is complete. Present only when `dataset = "traces"`.
        checked_at:
          $ref: '#/components/schemas/Timestamp'
      example:
        dataset: blocks
        category: raw
        max_block_number: 2000000
        max_day: null
        max_time: 2026-09-28 03:41:07+00:00
        seconds_behind: 0
        blocks_behind: null
        days_behind: null
        checked_at: 2026-09-28 03:41:10+00:00
    FreshnessEnvelope:
      type: object
      required:
      - data
      - meta
      description: '`next_cursor` is never present (this endpoint has no pagination).'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FreshnessRow'
        meta:
          allOf:
          - $ref: '#/components/schemas/Meta'
          - type: object
            properties:
              stale:
                type: boolean
                const: true
                description: Present (always `true`) only when this is the previous successful answer served because the refresh failed; absent on a freshly queried answer.
              stale_age_seconds:
                type: integer
                minimum: 0
                description: Present with `stale`; seconds since this answer was queried (at most 60).
    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'
    ChainStatus:
      type: object
      required:
      - chain
      - name
      - chain_id
      - jsonrpc
      - data
      - data_features
      - status
      - sync
      - head
      properties:
        chain:
          type: string
          description: Chain slug.
        name:
          type: string
          description: Human-readable display name.
        chain_id:
          type: integer
          description: Chain ID (decimal integer).
        jsonrpc:
          type: boolean
          description: Whether JSON-RPC is offered for this chain.
        data:
          type: boolean
          description: 'Whether the Data API is offered for this chain. This is not a fixed setting: the service reads the chain list of the Data API upstream service at most once every 30 seconds, and the value is `true` while a registered chain appears in that list and returns to `false` when it is removed from it; before the first successful read after the service starts, every chain is `false`.'
        data_features:
          type: array
          items:
            type: string
          description: Capabilities the Data API offers for this chain, with the same values and order as `features` of that chain in `GET /v1/data/chains`; an empty array when `data` is `false`. An endpoint that is not in the list returns 422 `no_coverage`.
          example:
          - blocks
          - transactions
          - address_transactions
          - transfers
          - token_metadata
          - freshness
        data_status:
          type: string
          enum:
          - ok
          - syncing
          - unavailable
          description: 'Run state of the Data API, as reported by the upstream data service. Present only when `data` is `true`. `ok`: the indexed data is fresh. `syncing`: the chain has data, but its newest indexed block is older than the freshness threshold of the data service (300 seconds by default, configurable per chain). `unavailable`: the data service reports the chain unavailable, or reports a status the service does not recognize. `syncing` and `unavailable` are informational: the Data API of the chain stays offered and its requests are forwarded and billed as usual. The field is omitted when `data` is `false`.'
        data_head_block:
          type:
          - integer
          - 'null'
          format: int64
          nullable: true
          description: Newest indexed block of the chain, as reported by the upstream data service; `null` when it reports none. Present only when `data` is `true`. It is not part of the refresh invalidation and can be up to about 60 seconds old.
        data_head_age_seconds:
          type:
          - integer
          - 'null'
          format: int64
          nullable: true
          description: Seconds between the time of `data_head_block` and the moment the upstream data service answered; `null` when it reports none. Present only when `data` is `true`. It is not part of the refresh invalidation and can be up to about 60 seconds old.
        status:
          type: string
          enum:
          - ok
          - unavailable
          description: Run state of the chain.
        sync:
          $ref: '#/components/schemas/ChainSync'
        head:
          $ref: '#/components/schemas/ChainHead'
    ChainSync:
      type: object
      description: Sync stage of the node and the blocks that show its progress.
      required:
      - stage
      - node_block
      - target_block
      properties:
        stage:
          type: string
          enum:
          - synced
          - syncing
          - unknown
          description: Node sync stage. `synced` means the node fully meets the health rule (the same rule as traffic admission, including block-time freshness); `syncing` means the latest successful probe returned an `eth_syncing` progress object and the health rule did not pass; `unknown` covers everything else (the first probe has not completed, the latest probe failed, the chain ID does not match, `eth_syncing` cannot be parsed, or `eth_syncing` is false but the health rule did not pass).
        node_block:
          type:
          - integer
          - 'null'
          nullable: true
          description: Current block height of the node (`currentBlock` of the `eth_syncing` progress object, or the latest block height when there is no progress object). null before the first probe completes.
        target_block:
          type:
          - integer
          - 'null'
          nullable: true
          description: Target block height. It is `highestBlock` when that is greater than `currentBlock`; otherwise, when the progress object contains a `stages` array, it is the largest `stages[].block` that is greater than `currentBlock`; in all other cases it is null.
    ChainHead:
      type:
      - object
      - 'null'
      nullable: true
      description: Latest block information of the node. null before the first successful probe, or when the node state is unknown (for example the block height is 0 or the timestamp is 0).
      required:
      - block
      - time
      - lag_seconds
      properties:
        block:
          type: integer
          description: Latest block height of the node.
        time:
          type: string
          format: date-time
          description: Timestamp of the latest block of the node (RFC 3339 / ISO 8601 UTC).
        lag_seconds:
          type: integer
          description: Seconds by which the block time lags the current time.
    StatusResponseBody:
      type: object
      required:
      - checked_at
      - gateway
      - chains
      properties:
        checked_at:
          type: string
          format: date-time
          description: Time the status snapshot was generated (RFC 3339 / ISO 8601 UTC).
        gateway:
          type: object
          required:
          - status
          properties:
            status:
              type: string
              enum:
              - ok
              - degraded
              description: Run state of the service process. `ok` means the process is ready; `degraded` means balance admission or key data is not ready yet or has expired, so paid requests are rejected, and it returns to `ok` automatically after recovery. It is independent of the node state of any chain; see `chains[].status` for chain state.
        chains:
          type: array
          items:
            $ref: '#/components/schemas/ChainStatus'
          description: Supported blockchains and the sync state of their nodes.
  examples:
    statusOk:
      summary: Public service status response
      value:
        checked_at: 2026-09-28 12:00:00+00:00
        gateway:
          status: ok
        chains:
        - chain: robinhood_mainnet
          name: Robinhood Chain
          chain_id: 4663
          jsonrpc: true
          data: true
          data_features:
          - blocks
          - transactions
          - address_transactions
          - transfers
          - token_metadata
          - freshness
          status: ok
          sync:
            stage: synced
            node_block: 73017329
            target_block: null
          head:
            block: 73017329
            time: 2026-09-28 11:59:58+00:00
            lag_seconds: 2
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your BlockVectra API key.
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <api_key>`. Only the prefixes `Bearer ` and `bearer ` are accepted. Used only when `x-api-key` is missing or empty.'
x-refined-from:
- data.yaml
- json-rpc.yaml