BlockVectra Chains API

openapi: 3.2.0
info:
  title: Blockvectra Chains API
  termsOfService: https://blockvectra.com/en/terms/
  version: '1.0'
  description: 'Operations tagged Chains across 2 of this provider''s published API definitions: json-rpc.yaml, push.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.blockvectra.com/v1
  description: BlockVectra JSON-RPC and Data API
tags:
- name: Chains
  description: Public list of served chains and their static parameters (Section 12).
paths:
  /chains:
    get:
      tags:
      - Chains
      operationId: getChains
      summary: Public chain list and parameters
      description: '`GET /v1/chains`. Public list of served chains and their static parameters (Section 12). It needs no authentication, is not billed and is not rate limited.


        **When to use**: use this operation to discover which chain slugs you can put in `/v1/{chain}`, and to read each chain''s EVM `chain_id`, the supported capabilities (`jsonrpc` and `data`), the method policy (`methods` allow and deny lists), the maximum `eth_getLogs` block range, the state window in blocks and the public info.


        **Behavior**: `chains[]` lists only the chains that are publicly served, sorted by chain slug. Data is refreshed at most every 60 seconds.


        **Request example**: `GET /v1/chains`


        **Response example**: the `chainsOk` example on the 200 response.


        **Errors**: this operation defines no error responses. The HTTP status is always 200. It is never billed. Retrying is always safe: the endpoint is read-only and free.'
      security: []
      responses:
        '200':
          $ref: '#/components/responses/ChainsOk'
    servers:
    - url: https://api.blockvectra.com/v1
      description: BlockVectra JSON-RPC and Data API
  /push/chains:
    get:
      tags:
      - Chains
      operationId: listPushChains
      summary: Chains open for push, with confirmation minimum, default and maximum and the…
      responses:
        '200':
          description: Chains open for push.
          headers:
            x-bv-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainList'
              examples:
                chains:
                  $ref: '#/components/examples/chains'
        default:
          $ref: '#/components/responses/Error'
      security:
      - ApiKeyHeader: []
    servers:
    - url: https://api.blockvectra.com/v1
      description: Gateway front door (x-api-key).
components:
  examples:
    chainsOk:
      summary: Public chain list and static parameters response
      value:
        chains:
        - chain: robinhood_mainnet
          name: Robinhood Chain
          chain_id: 4663
          jsonrpc: true
          data: true
          ws: false
          subscriptions: []
          methods:
            allow:
            - eth_blockNumber
            - eth_chainId
            - eth_gasPrice
            - eth_maxPriorityFeePerGas
            - eth_blobBaseFee
            - eth_feeHistory
            - eth_syncing
            - eth_getBalance
            - eth_getCode
            - eth_getStorageAt
            - eth_getTransactionCount
            - eth_call
            - eth_estimateGas
            - eth_createAccessList
            - eth_getProof
            - eth_simulateV1
            - eth_getBlockByNumber
            - eth_getBlockByHash
            - eth_getBlockReceipts
            - eth_getBlockTransactionCountByNumber
            - eth_getBlockTransactionCountByHash
            - eth_getTransactionByHash
            - eth_getTransactionReceipt
            - eth_getTransactionByBlockNumberAndIndex
            - eth_getTransactionByBlockHashAndIndex
            - eth_getRawTransactionByHash
            - eth_getRawTransactionByBlockHashAndIndex
            - eth_getRawTransactionByBlockNumberAndIndex
            - eth_getLogs
            - eth_getUncleCountByBlockNumber
            - eth_getUncleCountByBlockHash
            - eth_getUncleByBlockNumberAndIndex
            - eth_getUncleByBlockHashAndIndex
            - eth_getHeaderByNumber
            - eth_getHeaderByHash
            - eth_sendRawTransaction
            - net_version
            - web3_clientVersion
            - web3_sha3
            - debug_traceTransaction
            - debug_traceCall
            - debug_traceBlockByNumber
            - debug_traceBlockByHash
            deny:
            - eth_newFilter
            - eth_newBlockFilter
            - eth_newPendingTransactionFilter
            - eth_getFilterLogs
            - eth_getFilterChanges
            - eth_uninstallFilter
            - eth_subscribe
            - eth_unsubscribe
          max_logs_block_range: 1000
          state_window_blocks: 900
          transaction_lookup_window_blocks: null
          info: {}
          push: null
          public:
            scope: per_instance
            url: https://api.blockvectra.com/v1/robinhood_mainnet/public
            methods:
            - eth_chainId
            - eth_blockNumber
            - eth_getBalance
            - eth_call
            - eth_estimateGas
            - eth_gasPrice
            rate_limit:
              per_ip_rps: 3
              burst: 20
              batch_max: 10
            history_blocks: 900
            pool:
              cu_per_sec: 1250
              in_flight: 64
              heavy_in_flight: 4
    chains:
      value:
        chains:
        - chain: bsc_mainnet
          chain_id: 56
          min_confirmations: 1
          default_confirmations: 1
          max_confirmations: 2
          replayable_from_block: 63424000
          halted: false
        - chain: eth_mainnet
          chain_id: 1
          min_confirmations: 1
          default_confirmations: 6
          max_confirmations: 82
          replayable_from_block: 23480100
          halted: false
        - chain: base_mainnet
          chain_id: 8453
          min_confirmations: 1
          default_confirmations: 1
          max_confirmations: 519
          replayable_from_block: 38120000
          halted: false
        - chain: arb_mainnet
          chain_id: 42161
          min_confirmations: 1
          default_confirmations: 120
          max_confirmations: 120
          replayable_from_block: 390000000
          halted: false
        - chain: polygon_mainnet
          chain_id: 137
          min_confirmations: 1
          default_confirmations: 200
          max_confirmations: 200
          replayable_from_block: 80000000
          halted: false
  schemas:
    ChainsResponseBody:
      type: object
      required:
      - chains
      properties:
        chains:
          type: array
          items:
            $ref: '#/components/schemas/ChainFacts'
          description: Public chains and their static parameters.
    PushCapability:
      type:
      - object
      - 'null'
      description: 'Chain-level facts projected from the same catalogue as GET /v1/push/chains.

        null means the source is unavailable, incomplete, invalid, or unknown.

        Only a valid catalogue explicitly confirming completeness can establish supported=false; other members are then null.

        Unlisted chains remain unknown when the source cannot confirm completeness.

        Paused chains remain supported. Known confirmations satisfy min <= default <= max.

        These facts do not grant subscription permissions or promise finality. Results are fresh within 60 seconds;

        the Age response header indicates the elapsed seconds since the facts were sampled.

        '
      properties:
        supported:
          type:
          - boolean
          - 'null'
        min_confirmations:
          type:
          - integer
          - 'null'
          minimum: 1
        default_confirmations:
          type:
          - integer
          - 'null'
          minimum: 1
        max_confirmations:
          type:
          - integer
          - 'null'
          minimum: 1
        replayable_from_block:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 9007199254740991
          description: Replay lower bound; zero is a known block number.
        halted:
          type:
          - boolean
          - 'null'
          description: Whether reorganisation has halted the chain; null when unknown.
    PublicEndpointFacts:
      type: object
      description: Public endpoint requires no API key and is not billed. Request quotas, submission quotas, and pool limits apply independently per service instance and are not shared across instances.
      required:
      - scope
      - url
      - methods
      - rate_limit
      - history_blocks
      - pool
      properties:
        scope:
          type: string
          enum:
          - per_instance
          description: Request, submission, and public pool limits in this object apply independently per service instance and are not shared across instances.
        url:
          type: string
          format: uri
          description: Absolute HTTPS URL of the public JSON-RPC endpoint, generated by the service from its configured API base URL. Clients use this URL directly.
          example: https://api.blockvectra.com/v1/robinhood_mainnet/public
        methods:
          type: array
          items:
            type: string
          description: Wallet methods available on this chain's public endpoint.
        rate_limit:
          type: object
          description: Per-IP request quota shared across chains within each service instance; IPv4 uses the individual address and IPv6 uses /64. Each batch item consumes one token. Well-formed local eth_chainId calls with unambiguous member names and params omitted, null, or [] are exempt, including in mixed batches larger than 1 KiB (1024 bytes). Only an entire body of such eth_chainId calls exceeding 1 KiB (1024 bytes) consumes one token per item; exactly 1024 bytes remains exempt.
          required:
          - per_ip_rps
          - burst
          - batch_max
          properties:
            per_ip_rps:
              type: integer
              minimum: 1
              description: Default 3 requests/second per IP per instance (operator adjustable).
            burst:
              type: integer
              minimum: 1
              description: Default burst of 20 requests per IP per instance (operator adjustable).
            batch_max:
              type: integer
              minimum: 1
              description: Default at most 10 items per public batch (operator adjustable).
        send_raw_rate_limit:
          type: object
          description: 'The eth_sendRawTransaction IP quota is shared across chains within each service instance. By default each chain also has a per-instance submission bucket of 2/second with a burst of 2 (operator adjustable), so a public batch can contain at most as many such items as the bucket burst (2 by default); more can never pass the chain bucket. This object is omitted when public raw transaction submission is unavailable, including on HyperEVM.

            '
          required:
          - per_ip_rps
          - burst
          properties:
            per_ip_rps:
              type: integer
              minimum: 1
              description: Default 1 submission/second per IP per instance (operator adjustable).
            burst:
              type: integer
              minimum: 1
              description: Default burst of 3 submissions per IP per instance (operator adjustable).
        history_blocks:
          type: integer
          minimum: 0
        pool:
          type: object
          description: Public pool limits apply independently per chain per service instance. Public concurrency and heavy-method subpools are 25% of their corresponding chain limits (rounded down, minimum 1). Robinhood has a public pool of 1250 CU/second per instance; other chains limit concurrency only and omit cu_per_sec.
          required:
          - in_flight
          - heavy_in_flight
          properties:
            cu_per_sec:
              type: integer
              minimum: 1
              description: Public CU/second limit for this chain per instance.
            in_flight:
              type: integer
              minimum: 1
              description: Public in-flight call limit for this chain per instance.
            heavy_in_flight:
              type: integer
              minimum: 1
              description: Public heavy-method in-flight call limit for this chain per instance.
    ChainFacts:
      type: object
      required:
      - chain
      - name
      - chain_id
      - jsonrpc
      - data
      - methods
      - max_logs_block_range
      - state_window_blocks
      - info
      properties:
        push:
          $ref: '#/components/schemas/PushCapability'
        public:
          $ref: '#/components/schemas/PublicEndpointFacts'
        chain:
          type: string
          description: Chain slug.
          example: robinhood_mainnet
        name:
          type: string
          description: Human-readable display name.
          example: Robinhood
        chain_id:
          type: integer
          description: EIP-155 chain ID (decimal integer).
          example: 4663
        jsonrpc:
          type: boolean
          description: Whether JSON-RPC is offered for this chain.
          example: true
        data:
          type: boolean
          description: Whether the Data API is offered for this chain.
          example: true
        ws:
          type: boolean
          description: Whether WebSocket subscriptions are offered for this chain on this listener.
          example: true
        subscriptions:
          type: array
          items:
            type: string
          description: WebSocket subscription kinds available for this chain (empty when ws is false).
          example:
          - newHeads
          - logs
        methods:
          type: object
          required:
          - allow
          - deny
          properties:
            allow:
              type: array
              items:
                type: string
              description: Allowed methods, as exact names only (non-empty list; no wildcard -- every chain's allow list names concrete methods the chain's node was confirmed to support).
              example:
              - eth_call
              - eth_getBalance
              - net_version
            deny:
              type: array
              items:
                type: string
              description: Denied methods or prefix wildcards.
              example:
              - eth_newFilter
        max_logs_block_range:
          type: integer
          description: Maximum block span allowed in one `eth_getLogs` call.
          example: 1000
        state_window_blocks:
          type:
          - integer
          - 'null'
          nullable: true
          description: Size of the historical state window in blocks. null for full history (archive) or when there is no limit.
          example: 900
        transaction_lookup_window_blocks:
          type:
          - integer
          - 'null'
          nullable: true
          minimum: 0
          description: Registered transaction hash index window in blocks. Zero means no historical index; null means no registered limit and does not promise full history. Metadata only; transaction hash lookups preserve node null results regardless of this value.
          example: 600000
        info:
          type: object
          description: Public extension information of the chain (reserved; currently the empty object `{}`).
    ChainName:
      type: string
      pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)+$
      description: lower(chain_slug), ES-030 rule 10.
    BlockNumber:
      type: integer
      minimum: 0
    ErrorCode:
      type: string
      enum:
      - invalid_request
      - missing_api_key
      - invalid_api_key
      - insufficient_balance
      - key_expired
      - not_found
      - limit_reached
      - request_too_large
      - chain_not_available
      - chains_required
      - confirmations_out_of_range
      - destination_not_allowed
      - block_out_of_range
      - rate_limited
      - cost_exceeds_burst
      - key_cap_exhausted
      - internal_error
      - auth_unavailable
      - billing_unavailable
      - upstream_unavailable
      - service_unavailable
    ErrorReason:
      description: The fine-grained reason; equals the code except for the history admission reasons below.
      type: string
      enum:
      - invalid_request
      - missing_api_key
      - invalid_api_key
      - insufficient_balance
      - key_expired
      - not_found
      - limit_reached
      - request_too_large
      - chain_not_available
      - chains_required
      - confirmations_out_of_range
      - destination_not_allowed
      - block_out_of_range
      - rate_limited
      - cost_exceeds_burst
      - key_cap_exhausted
      - internal_error
      - auth_unavailable
      - billing_unavailable
      - upstream_unavailable
      - service_unavailable
      - request_exceeds_burst
      - balance_exhausted
      - free_grant_exhausted
      - key_rate_limit
      - free_plan_call_limit
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - data
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            data:
              type: object
              additionalProperties: false
              required:
              - reason
              - docs_url
              - retryable
              - request_id
              properties:
                reason:
                  $ref: '#/components/schemas/ErrorReason'
                docs_url:
                  type: string
                retryable:
                  type: boolean
                field:
                  type: string
                invalid:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - field
                    - reason
                    properties:
                      field:
                        type: string
                      reason:
                        type: string
                        enum:
                        - format
                        - checksum
                limit:
                  type: string
                  enum:
                  - subscriptions
                  - addresses_per_subscription
                  - address_pairs_per_account
                chain:
                  $ref: '#/components/schemas/ChainName'
                available:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChainName'
                  description: 'On chains_required at create: the chains open for push.'
                min:
                  type: integer
                max:
                  type: integer
                rule:
                  type: string
                  enum:
                  - scheme
                  - port
                  - ip_literal
                  - userinfo
                  - fragment
                  - reserved_host
                  - too_long
                  - invalid_url
                min_block:
                  $ref: '#/components/schemas/BlockNumber'
                max_block:
                  $ref: '#/components/schemas/BlockNumber'
                topup_url:
                  type: string
                  description: 'On insufficient_balance: the console billing page.'
                deposit_address_url:
                  type: string
                  description: 'On insufficient_balance: the deposit address page, when configured.'
                balance_units:
                  type: integer
                  description: 'On insufficient_balance: the remaining balance in ledger units (negative when overdrawn), when known.'
                balance_cu:
                  type: integer
                  description: 'On insufficient_balance: the remaining balance in CU, truncated toward zero, when known.'
                cu_cap:
                  type: integer
                  description: 'On key_cap_exhausted: the CU cap of the key.'
                request_id:
                  type: string
                  pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    ChainList:
      type: object
      additionalProperties: false
      required:
      - chains
      properties:
        chains:
          type: array
          items:
            $ref: '#/components/schemas/Chain'
    Chain:
      type: object
      additionalProperties: false
      required:
      - chain
      - chain_id
      - min_confirmations
      - default_confirmations
      - max_confirmations
      - replayable_from_block
      - halted
      properties:
        chain:
          $ref: '#/components/schemas/ChainName'
        chain_id:
          type: integer
          minimum: 1
        min_confirmations:
          type: integer
          minimum: 1
          description: Smallest N a subscription may choose on this chain (1).
        default_confirmations:
          type: integer
          minimum: 1
          description: N used when a request omits confirmations for this chain.
        max_confirmations:
          type: integer
          minimum: 1
          description: Largest N a subscription may choose on this chain.
        replayable_from_block:
          $ref: '#/components/schemas/BlockNumber'
        halted:
          type: boolean
          description: true while the chain is stopped after a chain reorg; subscriptions stay online; once operators restore the chain, each affected stream re-delivers canonical events from the fork point.
  responses:
    ChainsOk:
      description: 'Configured public chains and per-chain static facts. Unauthenticated, unmetered, unbilled,

        served with `Access-Control-Allow-Origin: *` and `Cache-Control: max-age=60` headers.

        '
      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=60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ChainsResponseBody'
          examples:
            chainsOk:
              $ref: '#/components/examples/chainsOk'
    Error:
      description: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.
      headers:
        x-bv-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      required: false
      description: Whole seconds; on 429 and 503.
      schema:
        type: integer
        minimum: 1
    RequestId:
      required: true
      description: UUIDv7 in the canonical 36-character form, generated by the gateway (opaque; a client value is ignored); repeated as error.data.request_id.
      schema:
        type: string
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key. When it is not empty it takes precedence over `Authorization`. Leading and trailing whitespace is trimmed.
    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:
- json-rpc.yaml
- push.yaml