openapi: 3.1.0
info:
  title: BlockVectra JSON-RPC API
  version: 2.2.3
  termsOfService: https://blockvectra.com/en/terms/
  description: "BlockVectra JSON-RPC 2.0 API. Send requests to `https://api.blockvectra.com/v1/robinhood_mainnet` with your API key in the `x-api-key` header, or put the key in the path: `/v1/{chain}/{api_key}`. All methods are metered in Compute Units (CU) and rate-limited per key."
servers:
  - url: https://api.blockvectra.com/v1
    description: BlockVectra JSON-RPC and Data API
tags:
  - name: JSON-RPC
    description: Ethereum-style JSON-RPC 2.0 calls to a chain node (Section 1).
  - name: Status
    description: Public service status (Section 14).
  - name: Chains
    description: Public list of served chains and their static parameters (Section 12).
  - name: Account
    description: Read-only lookup of the caller's own API key's balance and limits
      by x-api-key; never billed (Section 1).
  - name: Faucet
    description: Claim test ETH on the Robinhood testnet; claims are free.
paths:
  /faucet/robinhood_testnet:
    post:
      tags:
        - Faucet
      operationId: claimRobinhoodTestnetFaucet
      summary: Claim 0.001 test ETH on the Robinhood testnet.
      description: >
        `POST /v1/faucet/robinhood_testnet` serves only `robinhood_testnet`
        (chain ID `46630`). Authentication uses only `x-api-key`; path keys and
        `Authorization` are ignored. Claims are free: no usage is recorded, no
        CU is charged, and balance admission is skipped. Subsequent testnet RPC
        queries are billed normally.


        The request body contains only `address` and is limited to 64 KiB. An
        address must be `0x` followed by 40 hexadecimal characters, either
        lowercase or mixed case with a valid EIP-55 checksum; response addresses
        are lowercase. Unknown fields or invalid JSON return 400
        `invalid_request`. Other chains, extra path segments, percent signs in
        the path, query strings, or unsupported methods return 404 `not_found`.


        Each claim grants **0.001 test ETH** (`1000000000000000` wei). Each
        account and each address may claim **once per rolling 24 hours**, shared
        across keys; at most **1,000 claims per UTC day** are accepted globally.
        New customers with a valid API key may claim for a fresh address; no
        mainnet balance or transaction history is required.


        A 202 response means accepted, not confirmed on-chain. A retry by the
        same account for the same normalized address within 24 hours returns the
        original 202 response and transaction hash without sending more funds.
        Use testnet RPC to query the receipt. `next_eligible_at` is acceptance
        time plus 24 hours; it does not reset at UTC midnight.


        The front door shares a **5 requests per second per key** bucket with
        `/v1/account` and `/v1/push`. Front-door 429 responses omit
        `data.scope`; claim-limit 429 responses specify `account`, `address`, or
        `global`. Responses with status 429 or 503 include `Retry-After`; wait
        that many seconds before retrying. Claim results and error bodies are
        returned unchanged.


        Browsers may call from any origin. OPTIONS preflight returns 204 before
        authentication, using the same CORS request-header list as
        `/v1/account`. If the faucet is unavailable, the endpoint returns 404
        `not_found`.
      security:
        - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FaucetClaimRequest"
            example:
              address: "0x1111111111111111111111111111111111111111"
      responses:
        "202":
          description: Accepted, or the original acceptance result for this account and
            address; free of charge.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                  - no-store
            Access-Control-Allow-Origin:
              schema:
                type: string
                enum:
                  - "*"
            x-bv-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}$
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetClaimAccepted"
              example:
                chain: robinhood_testnet
                chain_id: 46630
                address: "0x1111111111111111111111111111111111111111"
                amount_wei: "1000000000000000"
                tx_hash: "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
                next_eligible_at: 2026-10-05T08:00:00Z
        "400":
          description: "`invalid_address` (`data.field = /address`) or `invalid_request`; correct the request before retrying."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
        "401":
          description: "`missing_api_key` or `invalid_api_key`; check the API key."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
        "403":
          description: "`key_expired`; use a valid API key before retrying."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
              example:
                error:
                  code: key_expired
                  message: key expired
                  data:
                    reason: key_expired
                    docs_url: https://docs.blockvectra.com/en/errors/#key_expired
                    retryable: false
                    request_id: 0193a5c2-7e4b-7d3a-9f10-4c5b6a7d8e9f
        "404":
          description: "`not_found`; unsupported path, chain, method, or query string, or faucet unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
        "413":
          description: "`request_too_large`; request body exceeds 64 KiB."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
        "429":
          description: "`rate_limited`; front-door rate limits omit scope, while claim limits include `data.scope = account | address | global` and `next_eligible_at`."
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
        "503":
          description: >
            `faucet_empty` (insufficient faucet funds, Retry-After 60),
            `service_unavailable` (dependencies unavailable: 60; previous claim
            has no receipt yet or claim processing is busy: 5),
            `auth_unavailable` (stale authentication data; wait for refresh), or
            `upstream_unavailable` (forwarding unavailable, Retry-After 1).
            Retry after the indicated delay; without explicit acceptance, do not
            assume funds were sent.
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
              example:
                error:
                  code: faucet_empty
                  message: faucet empty
                  data:
                    reason: faucet_empty
                    docs_url: https://docs.blockvectra.com/en/errors/#faucet_empty
                    retryable: true
                    request_id: 0193a5c2-7e4b-7d3a-9f10-4c5b6a7d8e9f
    options:
      tags:
        - Faucet
      operationId: preflightRobinhoodTestnetFaucet
      summary: CORS preflight for browser faucet claim requests, without an API key.
      security: []
      responses:
        "204":
          description: Preflight accepted; no authentication, rate-limit consumption, or
            billing.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                enum:
                  - "*"
            Access-Control-Allow-Methods:
              schema:
                type: string
                enum:
                  - GET, POST, OPTIONS
            Access-Control-Allow-Headers:
              schema:
                type: string
                enum:
                  - content-type, x-api-key, x-bv-meter
            Access-Control-Max-Age:
              schema:
                type: integer
                enum:
                  - 86400
        "404":
          description: "`not_found`; faucet unavailable."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaucetError"
  /{chain}/public:
    post:
      tags:
        - JSON-RPC
      operationId: rpcPublic
      summary: Call the public wallet JSON-RPC endpoint without an API key.
      description: >
        Every chain serving public JSON-RPC supports `POST /v1/{chain}/public`
        without a key or billing. Available methods and current limits are
        published in the `public` object of `GET /v1/chains`.


        Request quotas, transaction submission quotas, and public pool limits
        below apply independently per service instance and are not shared across
        instances. Each IP shares 3 requests/second with a burst of 20 across
        chains on the same instance; IPv4 uses the individual address and IPv6
        uses /64. Batches contain at most 10 items, each consuming one request
        token. Well-formed local `eth_chainId` calls with unambiguous member
        names and params omitted, null, or [] do not consume request tokens,
        including in mixed batches larger than 1 KiB (1024 bytes). Only when the
        entire body consists of such `eth_chainId` calls and exceeds 1 KiB (1024
        bytes) does each item consume a request token; a body of exactly 1024
        bytes remains exempt. `eth_sendRawTransaction` also has a per-IP limit
        of 1/second with a burst of 3, plus a per-chain, per-instance limit of
        2/second with a burst of 2. A public batch can therefore contain at most
        2 `eth_sendRawTransaction` items; larger counts can never pass the chain
        submission bucket. HyperEVM does not offer this method, and no chain
        offers `eth_sendRawTransactionSync`.


        Each chain has public concurrency and heavy-method subpools equal to 25%
        of its corresponding total limits (rounded down, minimum 1). The
        `public.pool.in_flight`, `heavy_in_flight`, and optional `cu_per_sec`
        fields of `GET /v1/chains` are per-instance limits. Robinhood has a
        public pool of 1250 CU/second per instance; other chains limit
        concurrency only and omit `cu_per_sec`.


        Only wallet methods are allowed, intersected with each chain's method
        policy: `eth_chainId`, `net_version`, `eth_blockNumber`,
        `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`,
        `eth_getStorageAt`, `eth_call`, `eth_estimateGas`, `eth_gasPrice`,
        `eth_maxPriorityFeePerGas`, `eth_feeHistory`, `eth_getBlockByNumber`,
        `eth_getBlockByHash`, `eth_getTransactionByHash`,
        `eth_getTransactionReceipt`, `eth_syncing`, `web3_clientVersion`,
        `eth_sendRawTransaction`. Other methods return -32601 with reason
        `method_not_public`.


        All block-number references are restricted to the most recent 1000
        blocks or the chain state window, whichever is smaller, including block
        queries and the earliest block covered by `eth_feeHistory`. State
        queries using `blockHash` are rejected. References outside the window
        return -32011 with reason `state_window`.


        A full public pool or rate limit returns HTTP 429, an integer
        `Retry-After`, and -32005. The reason is `public_rate_limit` (IP quota)
        or `public_pool_busy` (chain public pool). `error.data.signup_url` and
        `account_url` include `?ref=public` and point to browser signup and
        programmatic signup respectively. Responses include `x-bv-tier: public`
        and `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`,
        `RateLimit-Policy`.


        The public endpoint returns the node answer only and has no history
        fallback: an unknown transaction hash returns `null` here, as it does on
        a keyed request. Supplying `x-api-key` or `Authorization: Bearer` uses
        normal authentication and billing; path keys may use
        `/v1/{chain}/public/{api_key}`. The regular RPC paths, WebSocket, and
        Data API still require authentication. The public endpoint does not
        persist client IP addresses.
      security: []
      parameters:
        - $ref: "#/components/parameters/ChainPath"
      requestBody:
        $ref: "#/components/requestBodies/JsonRpcBody"
      responses:
        "200":
          description: JSON-RPC response or per-call method/history refusal; never billed
            without a key.
          headers:
            x-bv-tier:
              schema:
                type: string
                enum:
                  - public
            RateLimit-Limit:
              schema:
                type: integer
            RateLimit-Remaining:
              schema:
                type: integer
            RateLimit-Reset:
              schema:
                type: integer
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponseBody"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFoundPathKey"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          description: Public IP quota exhausted or public chain pool busy; not billed.
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
            x-bv-tier:
              schema:
                type: string
                enum:
                  - public
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcErrorResponse"
  /{chain}/public/{apiKey}:
    post:
      tags:
        - JSON-RPC
      operationId: rpcPublicWithPathKey
      summary: Call standard billed JSON-RPC through the public endpoint with a path
        API key.
      description: >
        `POST /v1/{chain}/public/{api_key}` uses the path API key with the
        normal authentication, rate limits, method policy, and billing of `POST
        /v1/{chain}/{apiKey}`. Only the path key is used; `x-api-key` and
        `Authorization` headers are ignored. Request and response schemas,
        status codes, and error examples match that regular path. Calls are
        billed at their method CU weight after an answer is received (Section
        8).


        `POST /v1/{chain}/public` without a path key also uses normal
        authentication and billing when `x-api-key` or `Authorization: Bearer`
        is supplied.
      security: []
      parameters:
        - $ref: "#/components/parameters/ChainPath"
        - $ref: "#/components/parameters/ApiKeyPath"
      requestBody:
        $ref: "#/components/requestBodies/JsonRpcBody"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFoundPathKey"
        "408":
          $ref: "#/components/responses/RequestTimeout"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
  /{chain}/{apiKey}:
    post:
      tags:
        - JSON-RPC
      operationId: rpcWithPathKey
      summary: JSON-RPC call (API key in the URL path)
      description: >
        `POST /v1/{chain}/{api_key}`. Sends one JSON-RPC 2.0 call, or a batch of
        calls, to the chain named by the chain slug `{chain}`. The API key is
        part of the URL path.


        **When to use**: use this form when your client can only build a URL and
        cannot set request headers, for example a wallet or library that accepts
        a single RPC URL. If you can set request headers, `POST /v1/{chain}`
        sends the key in a header instead.


        **Behavior**: `{chain}` is the chain slug of a served chain (list them
        with `GET /v1/chains`). An unknown chain slug returns 404 with a fixed
        error object (`unknown_chain`, with CORS headers) before the request
        body is read and before the key is looked up. Only the key in the path
        is used; the `x-api-key` and `Authorization` request headers are
        ignored. `POST /v1` (no trailing slash) and `POST /v1/{chain}/`
        (trailing slash, no key) fall through to the fallback: 404 with an empty
        body, with CORS headers, not billed. Every status code and example under
        this operation also applies to `POST /v1/{chain}` (key in a header);
        only the location of the key differs.


        **Billing**: a call is billed only after it has been answered, at the CU
        weight of its method. The weights are published by `GET /v1/plans`. See
        Section 8.


        **Request example** (`POST /v1/robinhood_mainnet/{api_key}`):


        ```json

        {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}

        ```


        **Response example** (HTTP 200):


        ```json

        {"jsonrpc": "2.0", "id": 1, "result": "0x45a27f1"}

        ```


        **Errors**: every error this operation can return is listed below with
        whether it is billed and whether it is retryable. "Retryable" means that
        sending the same request again can succeed without changing it; "No"
        says what must change first.


        HTTP-level responses (produced by the service, empty body):


        | HTTP | Cause | Billed | Retryable |

        |---:|---|---|---|

        | 400 | Malformed HTTP message (invalid chunked encoding, or the body
        stalls for more than 10 s between two reads; headers too large returns
        431 and URI too long returns 414) | No | No: fix the request first |

        | 403 | HTTP method other than `POST`, `GET`, `HEAD` and `OPTIONS`
        (empty 403 for known and unknown chains) | No | No: use `POST` |

        | 404 | A path that matches no operation (for example `POST /v1` or
        `POST /rpc`) | No | No: check the path |

        | 408 | No complete response within 35 s after the request headers were
        received | Possibly: the calls may already have reached the node and
        been billed | With care: do not retry calls that change state (such as
        `eth_sendRawTransaction`) without checking first |

        | 413 | Request body larger than 2 MiB | No | No: send a smaller body |


        JSON-RPC errors (the body is a JSON-RPC error object; the codes and
        messages are those of Section 4):


        | HTTP | Error | Billed | Retryable |

        |---:|---|---|---|

        | 200 | `-32700` `parse error` (service) | No (1 CU is taken from the
        rate-limit bucket) | No: send valid JSON |

        | 200 | `-32600` `invalid request` (service, reason `invalid_request`) |
        No (1 CU is taken from the rate-limit bucket) | No: send a valid
        JSON-RPC request |

        | 200 | `-32600` `batch too large: max <N> calls` (service, reason
        `batch_too_large` (+max)) | No | No: split the batch |

        | 200 | `-32600` `invalid request: ambiguous member name` (service,
        reason `invalid_request`) | No | No: use the exact member names
        `jsonrpc`, `id`, `method`, `params` |

        | 200 | `-32601` `method not available: <method>` (service) | No | No:
        use an allowed method |

        | 404 | `-32600` `unknown chain` (service, reason `unknown_chain`) | No
        | No: use a chain slug from `GET /v1/chains` |

        | 200 | `-32602` `eth_getLogs block range too large: max <N> blocks`
        (service) | No | No: query a smaller block range |

        | 200 | `-32602` `tracer not allowed` (service) | No | No: use an
        allowed tracer |

        | 200 | `-32602` `trace timeout not allowed` (service) | No | No: use a
        valid `timeout` |

        | 200 | `-32010` `node is syncing; calls are temporarily unavailable`
        (service) | No | Yes: retry later, the node is catching up |

        | 200 | `-32011` `historical state is not available beyond the most
        recent <N> blocks` (service) | No | No: use a block inside the state
        window |

        | 200 | `-32011` `requested history is not completely indexed` (service,
        reason `range_not_indexed`) | No | No: the requested history is not
        covered |

        | 200 | `-32011` `requested history is not ready` (service, reason
        `history_not_ready`) | No | Yes: retry after indexing catches up |

        | 200 | `-32000` `transaction not found` (service, reason `not_found`) |
        No | No, unless the transaction is expected to appear later |

        | 200 | `-32000` `block not found` (service, reason `not_found`) | No |
        No, unless the block is expected to appear later |

        | 200 | `-32000` `upstream response too large` (service, reason
        `response_too_large`) | No | No: request less data per call or per batch
        |

        | 200 | `-32005` `service overloaded, retry later` (service, reason
        `overloaded`) | No | Yes: retry later with backoff |

        | 503 | `-32005` `service overloaded, retry later` (service, reason
        `overloaded`, sent with `Retry-After`; the whole request was refused
        because the service had no room to hold its body) | No | Yes: retry
        after `Retry-After` |

        | 429 | `-32005` `rate limit exceeded` (service, reason `key_rate_limit`
        / `free_plan_call_limit` / `concurrency_limit`) | No | Yes: retry after
        `Retry-After` |

        | 429 | `-32022` `request cost <N> CU exceeds burst capacity <M> CU`
        (service, reason `request_exceeds_burst`) | No | No: split the request
        into smaller requests |

        | 429 | `-32022` `request has <N> calls, exceeding the free-plan limit
        of <M> calls per second` (service, reason `free_plan_batch_too_large`
        (+max)) | No | No: split the request into smaller requests |

        | 200 | `-32603` `upstream unavailable` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `no response from upstream` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `malformed upstream response` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `unexpected service error` (service) | No | Yes: retry,
        this is very rare |

        | 402 | `-32020` `insufficient balance` (service, reason
        `balance_exhausted` / `free_grant_exhausted`) | No | No: retry only
        after the account has been topped up |

        | 503 | `-32021` `billing data temporarily unavailable` (service) | No |
        Yes: retry after `Retry-After` seconds |

        | 200 | `4444` `pruned history unavailable` (node) | No | No: the
        requested block has been pruned |

        | 200 | `-32000` `historical state ... is not available` (node) | No |
        No: use a block inside the state window |

        | 200 | `-32000` `old data not available due to pruning...` (node) | No
        (Erigon, Ethereum mainnet) | No: use a block inside the state window |

        | 200 | `-32000` `missing trie node ...` (node) | No | No: use a block
        inside the state window; the node does not hold that state |

        | 200 | `-32002` `<node message>` (node) | No | Yes: retry with fewer
        calls per batch |

        | 200 | `-32003` `<node message>` (node) | No | Yes: retry with fewer
        calls per batch |

        | 200 | `-32600` `<node message>` (node) | No | Yes: retry with a
        smaller batch |

        | 200 | other error code `<node message>` (node) | **Yes** (method
        weight) | Depends on the node message. Deterministic errors such as
        `execution reverted` fail again |



        For these two RPC routes only: OPTIONS returns an empty 204 without
        looking up the chain or key. GET/HEAD first resolve the public chain;
        unknown or non-public chains return 404 unknown_chain. On a known public
        chain, a plain GET returns 405 with Allow: POST and a JSON-RPC -32600
        error whose error.data.reason is method_not_allowed; HEAD returns the
        same status and header with no wire body. A valid WebSocket upgrade
        instead follows separate capability, authentication and admission
        checks; a known chain alone does not guarantee 101. Methods other than
        POST, GET, HEAD and OPTIONS return an empty 403 for both known and
        unknown chains. POST resolves unknown or non-public chains to 404
        unknown_chain before authentication or body processing. Preflight and
        these refusals are not billed.
      security: []
      parameters:
        - $ref: "#/components/parameters/ChainPath"
        - $ref: "#/components/parameters/ApiKeyPath"
      requestBody:
        $ref: "#/components/requestBodies/JsonRpcBody"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFoundPathKey"
        "408":
          $ref: "#/components/responses/RequestTimeout"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
  /{chain}:
    post:
      tags:
        - JSON-RPC
      operationId: rpcWithHeaderKey
      summary: JSON-RPC call (API key in a header)
      description: >
        `POST /v1/{chain}`. Sends one JSON-RPC 2.0 call, or a batch of calls, to
        the chain named by the chain slug `{chain}`. The API key goes in the
        `x-api-key` header or the `Authorization: Bearer` header. A non-empty
        `x-api-key` wins over `Authorization`.


        **When to use**: use this form when your client can set request headers
        and you prefer not to put the key in the URL. It behaves exactly like
        `POST /v1/{chain}/{apiKey}`, so every status code and example listed
        there (400, 401, 402, 403, 408, 413, 429, 503 and so on) also applies
        here; only the way the key is sent differs.


        **Behavior**: `{chain}` is the chain slug of a served chain (list them
        with `GET /v1/chains`). An unknown chain slug returns 404 with a fixed
        error object (`unknown_chain`, with CORS headers) before the request
        body is read and before the key is looked up. On a known chain, no key
        at all returns 401 (`-32024`, reason `missing_api_key`, decided before
        any key lookup); an unknown, disabled or revoked key returns 401
        (`-32024`, reason `invalid_api_key`). If `x-api-key` is present and not
        empty, it is used even when it is wrong and `Authorization` is ignored.


        **Billing**: a call is billed only after it has been answered, at the CU
        weight of its method. The weights are published by `GET /v1/plans`. See
        Section 8.


        **Request example** (`POST /v1/robinhood_mainnet` with the header
        `x-api-key: <api_key>`):


        ```json

        {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}

        ```


        **Response example** (HTTP 200):


        ```json

        {"jsonrpc": "2.0", "id": 1, "result": "0x45a27f1"}

        ```


        **Errors**: every error this operation can return is listed below with
        whether it is billed and whether it is retryable. "Retryable" means that
        sending the same request again can succeed without changing it; "No"
        says what must change first.


        HTTP-level responses (produced by the service, empty body unless noted):


        | HTTP | Cause | Billed | Retryable |

        |---:|---|---|---|

        | 400 | Malformed HTTP message (invalid chunked encoding, or the body
        stalls for more than 10 s between two reads; headers too large returns
        431 and URI too long returns 414) | No | No: fix the request first |

        | 401 | JSON body, `-32024` `missing API key: ...` (reason
        `missing_api_key`): known chain, no `x-api-key` and no `Authorization:
        Bearer` header | No | No: send an API key |

        | 401 | JSON body, `-32024` `invalid API key: ...` (reason
        `invalid_api_key`): known chain, an unknown, disabled or revoked key |
        No | No: check the API key in the console |

        | 403 | HTTP method other than `POST`, `GET`, `HEAD` and `OPTIONS`
        (empty 403 for known and unknown chains) | No | No: use `POST` |

        | 404 | A path that matches no operation (for example `POST /v1` or
        `POST /rpc`) | No | No: check the path |

        | 408 | No complete response within 35 s after the request headers were
        received | Possibly: the calls may already have reached the node and
        been billed | With care: do not retry calls that change state (such as
        `eth_sendRawTransaction`) without checking first |

        | 413 | Request body larger than 2 MiB | No | No: send a smaller body |


        JSON-RPC errors (the body is a JSON-RPC error object; the codes and
        messages are those of Section 4):


        | HTTP | Error | Billed | Retryable |

        |---:|---|---|---|

        | 200 | `-32700` `parse error` (service, reason `parse_error`) | No (1
        CU is taken from the rate-limit bucket) | No: send valid JSON |

        | 200 | `-32600` `invalid request` (service, reason `invalid_request`) |
        No (1 CU is taken from the rate-limit bucket) | No: send a valid
        JSON-RPC request |

        | 200 | `-32600` `batch too large: max <N> calls` (service, reason
        `batch_too_large` (+max)) | No | No: split the batch |

        | 200 | `-32600` `invalid request: ambiguous member name` (service,
        reason `invalid_request`) | No | No: use the exact member names
        `jsonrpc`, `id`, `method`, `params` |

        | 200 | `-32601` `method not available: <method>` (service, reason
        `method_not_allowed`) | No | No: use an allowed method |

        | 404 | `-32600` `unknown chain` (service, reason `unknown_chain`) | No
        | No: use a chain slug from `GET /v1/chains` |

        | 200 | `-32602` `eth_getLogs block range too large: max <N> blocks`
        (service, reason `logs_range_too_large`) | No | No: query a smaller
        block range |

        | 200 | `-32602` `tracer not allowed` (service, reason `invalid_params`)
        | No | No: use an allowed tracer |

        | 200 | `-32602` `trace timeout not allowed` (service, reason
        `invalid_params`) | No | No: use a valid `timeout` |

        | 200 | `-32010` `node is syncing; calls are temporarily unavailable`
        (service, reason `node_syncing`) | No | Yes: retry later, the node is
        catching up |

        | 200 | `-32011` `historical state is not available beyond the most
        recent <N> blocks` (service, reason `state_window`) | No | No: use a
        block inside the state window |

        | 200 | `-32011` `requested history is not completely indexed` (service,
        reason `range_not_indexed`) | No | No: the requested history is not
        covered |

        | 200 | `-32011` `requested history is not ready` (service, reason
        `history_not_ready`) | No | Yes: retry after indexing catches up |

        | 200 | `-32000` `transaction not found` (service, reason `not_found`) |
        No | No, unless the transaction is expected to appear later |

        | 200 | `-32000` `block not found` (service, reason `not_found`) | No |
        No, unless the block is expected to appear later |

        | 200 | `-32000` `upstream response too large` (service, reason
        `response_too_large`) | No | No: request less data per call or per batch
        |

        | 200 | `-32005` `service overloaded, retry later` (service, reason
        `overloaded`) | No | Yes: retry later with backoff |

        | 503 | `-32005` `service overloaded, retry later` (service, reason
        `overloaded`, sent with `Retry-After`; the whole request was refused
        because the service had no room to hold its body) | No | Yes: retry
        after `Retry-After` |

        | 429 | `-32005` `rate limit exceeded` (service, reason `key_rate_limit`
        / `free_plan_call_limit` / `concurrency_limit`) | No | Yes: retry after
        `Retry-After` |

        | 429 | `-32022` `request cost <N> CU exceeds burst capacity <M> CU`
        (service, reason `request_exceeds_burst`) | No | No: split the request
        into smaller requests |

        | 429 | `-32022` `request has <N> calls, exceeding the free-plan limit
        of <M> calls per second` (service, reason `free_plan_batch_too_large`
        (+max)) | No | No: split the request into smaller requests |

        | 200 | `-32603` `upstream unavailable` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `no response from upstream` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `malformed upstream response` (service, reason
        `upstream_unavailable`) | No | Yes: retry with backoff |

        | 200 | `-32603` `unexpected service error` (service, reason
        `internal_error`) | No | Yes: retry, this is very rare |

        | 402 | `-32020` `insufficient balance` (service, reason
        `balance_exhausted` / `free_grant_exhausted`, `error.data.topup_url`
        set) | No | No: retry only after the account has been topped up |

        | 401 | `-32024` `missing API key: send it in the request path
        (/v1/{chain}/<api_key>) or in the x-api-key header` (service, reason
        `missing_api_key`) | No | No: send an API key |

        | 403 | `-32025` `API key expired; ...` (service, reason `key_expired`)
        or `API key CU cap exhausted; ...` (service, reason `key_cap_exhausted`,
        `error.data.cu_cap` set) | No | No: create a new key in the console |

        | 503 | `-32021` `authentication data temporarily unavailable` (service,
        reason `auth_unavailable`) | No | Yes: retry after `Retry-After` seconds
        |

        | 503 | `-32021` `billing data temporarily unavailable` (service, reason
        `billing_unavailable`) | No | Yes: retry after `Retry-After` seconds |

        | 200 | `4444` `pruned history unavailable` (node) | No | No: the
        requested block has been pruned |

        | 200 | `-32000` `historical state ... is not available` (node) | No |
        No: use a block inside the state window |

        | 200 | `-32000` `old data not available due to pruning...` (node) | No
        (Erigon, Ethereum mainnet) | No: use a block inside the state window |

        | 200 | `-32000` `missing trie node ...` (node) | No | No: use a block
        inside the state window; the node does not hold that state |

        | 200 | `-32002` `<node message>` (node) | No | Yes: retry with fewer
        calls per batch |

        | 200 | `-32003` `<node message>` (node) | No | Yes: retry with fewer
        calls per batch |

        | 200 | `-32600` `<node message>` (node) | No | Yes: retry with a
        smaller batch |

        | 200 | other error code `<node message>` (node) | **Yes** (method
        weight) | Depends on the node message. Deterministic errors such as
        `execution reverted` fail again |



        For these two RPC routes only: OPTIONS returns an empty 204 without
        looking up the chain or key. GET/HEAD first resolve the public chain;
        unknown or non-public chains return 404 unknown_chain. On a known public
        chain, a plain GET returns 405 with Allow: POST and a JSON-RPC -32600
        error whose error.data.reason is method_not_allowed; HEAD returns the
        same status and header with no wire body. A valid WebSocket upgrade
        instead follows separate capability, authentication and admission
        checks; a known chain alone does not guarantee 101. Methods other than
        POST, GET, HEAD and OPTIONS return an empty 403 for both known and
        unknown chains. POST resolves unknown or non-public chains to 404
        unknown_chain before authentication or body processing. Preflight and
        these refusals are not billed.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ChainPath"
      requestBody:
        $ref: "#/components/requestBodies/JsonRpcBody"
      responses:
        "200":
          description: JSON-RPC response. Same as the 200 of `POST /v1/{chain}/{apiKey}`;
            only the examples that depend on header authentication are listed
            here.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponseBody"
              examples:
                okXApiKey:
                  $ref: "#/components/examples/okXApiKey"
                okBearer:
                  $ref: "#/components/examples/okBearer"
                okEmptyXApiKeyFallsBackToBearer:
                  $ref: "#/components/examples/okEmptyXApiKeyFallsBackToBearer"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFoundPathKey"
        "408":
          $ref: "#/components/responses/RequestTimeout"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
  /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"
  /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"
  /account:
    get:
      tags:
        - Account
      operationId: getAccount
      summary: Get the API key's own balance and limits.
      description: >
        `GET /v1/account`. Returns the balance and limits of the API key sent in
        `x-api-key`. This operation is itself free: it is never billed, carries
        no usage row, and answers 200 with the current balance even when it is
        zero or negative (it never returns 402).


        **When to use**: use this operation to check an account's remaining
        balance and a key's rate limits and CU cap without spending CU on a
        billed call.


        **Behavior**: the key is read from the `x-api-key` request header only
        (a path key or `Authorization: Bearer` key is never read), exactly like
        the Data API, unlike the JSON-RPC lane, which also reads a path key and
        a Bearer key. This operation has its own request-rate limit, 5 requests
        per second per key id per service instance, independent of CU and
        billing; going over it returns 429. The response never carries a numeric
        account id, only the key's own `key_id`.


        **Request example**: `GET /v1/account` with the header `x-api-key:
        <api_key>`.


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


        **Errors**: every error this operation can return is listed below. It is
        never billed, so every error (and every 200) is unbilled alike.


        | HTTP | Error | Retryable |

        |---:|---|---|

        | 401 | `missing_api_key` (no header) or `invalid_api_key` (unknown,
        disabled or revoked) | No: check the API key |

        | 403 | `key_expired`: a valid key past its expiry | No: create a new
        key in the console |

        | 429 | `rate_limited` (5 requests/second per key id, per service
        instance), sent with `Retry-After` | Yes: retry after `Retry-After` |

        | 503 | `auth_unavailable` (key store stale) or `billing_unavailable`
        (billing data stale or not yet loaded), sent with `Retry-After` | Yes:
        retry after `Retry-After` |
      security:
        - ApiKeyHeader: []
      responses:
        "200":
          $ref: "#/components/responses/AccountOk"
        "401":
          $ref: "#/components/responses/AccountError"
        "403":
          $ref: "#/components/responses/AccountError"
        "429":
          $ref: "#/components/responses/AccountRetryableError"
        "503":
          $ref: "#/components/responses/AccountRetryableError"
components:
  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."
  parameters:
    ChainPath:
      name: chain
      in: path
      required: true
      description: Chain name, the same as in the Data API, e.g. `robinhood_mainnet`.
        The same API key works on every supported chain.
      schema:
        type: string
        pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)+$
      example: robinhood_mainnet
    ApiKeyPath:
      name: apiKey
      in: path
      required: true
      description: Your API key (`rgw_` followed by 64 hex characters). Under a known
        chain, an unknown, disabled or revoked key returns 401 with the JSON-RPC
        envelope (`-32024`, reason `invalid_api_key`).
      schema:
        type: string
        minLength: 1
      example: rgw_4f2d0c3b9a8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928170605f4
  requestBodies:
    JsonRpcBody:
      required: true
      description: A single JSON-RPC call object, or a batch array of 1 to 100 calls.
        At most 2 MiB.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcRequestBody"
          examples:
            reqBlockNumber:
              $ref: "#/components/examples/reqBlockNumber"
            reqChainId:
              $ref: "#/components/examples/reqChainId"
            reqBatch:
              $ref: "#/components/examples/reqBatch"
            reqEthCall:
              $ref: "#/components/examples/reqEthCall"
            reqMixedBatch:
              $ref: "#/components/examples/reqMixedBatch"
            reqNotifications:
              $ref: "#/components/examples/reqNotifications"
            reqSubscribe:
              $ref: "#/components/examples/reqSubscribe"
            reqAmbiguousMember:
              $ref: "#/components/examples/reqAmbiguousMember"
            reqEmptyBatch:
              $ref: "#/components/examples/reqEmptyBatch"
            reqMissingMethod:
              $ref: "#/components/examples/reqMissingMethod"
            reqBalanceOutsideWindow:
              $ref: "#/components/examples/reqBalanceOutsideWindow"
            reqLogsTooWide:
              $ref: "#/components/examples/reqLogsTooWide"
            reqTraceUnknownTx:
              $ref: "#/components/examples/reqTraceUnknownTx"
            reqTraceTx:
              $ref: "#/components/examples/reqTraceTx"
            reqPrunedBlock:
              $ref: "#/components/examples/reqPrunedBlock"
            reqTxReceipt:
              $ref: "#/components/examples/reqTxReceipt"
            reqBlockNumberBatch3:
              $ref: "#/components/examples/reqBlockNumberBatch3"
            reqEthCallBatch3:
              $ref: "#/components/examples/reqEthCallBatch3"
  responses:
    Ok:
      description: >
        JSON-RPC response: a single response object for a single request, or an
        array in request order for a batch (notifications take no slot).

        Each response element has either a `result` or an `error`. Every
        JSON-RPC level error (including the request-level `-32700` and

        `-32600`) is returned inside an HTTP 200. Billed: per call, as described
        in Section 8. Retryable: depends on the error, see the table in Section
        4.
      headers:
        x-bv-cu-charged:
          description: Returned only when the request sends the header x-bv-meter with
            value 1. The CU billed for this request (the sum over the billed
            calls of a batch). Absent when nothing was billed.
          schema:
            type: integer
            minimum: 0
        x-bv-balance-units:
          description: Returned only when the request sends the header x-bv-meter with
            value 1. The account's remaining balance units right after this
            charge (negative when overdrawn). The settled account balance minus
            total unsettled account usage rounded up to whole units once; hourly
            settlement rounds down so the balance can rise by up to one unit
            after settlement. Absent when nothing was billed, when balance
            admission is not active or when the balance is not known yet.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcResponseBody"
          examples:
            okSingle:
              $ref: "#/components/examples/okSingle"
            okBatch:
              $ref: "#/components/examples/okBatch"
            okChainId:
              $ref: "#/components/examples/okChainId"
            okMixedBatch:
              $ref: "#/components/examples/okMixedBatch"
            errParse:
              $ref: "#/components/examples/errParse"
            errInvalidRequestEmptyBatch:
              $ref: "#/components/examples/errInvalidRequestEmptyBatch"
            errInvalidRequestNoMethod:
              $ref: "#/components/examples/errInvalidRequestNoMethod"
            errBatchTooLarge:
              $ref: "#/components/examples/errBatchTooLarge"
            errAmbiguousMember:
              $ref: "#/components/examples/errAmbiguousMember"
            errMethodNotAvailable:
              $ref: "#/components/examples/errMethodNotAvailable"
            errNodeSyncing:
              $ref: "#/components/examples/errNodeSyncing"
            errOutsideStateWindow:
              $ref: "#/components/examples/errOutsideStateWindow"
            errLogsRangeTooLarge:
              $ref: "#/components/examples/errLogsRangeTooLarge"
            errTraceTxNotFound:
              $ref: "#/components/examples/errTraceTxNotFound"
            errNodeExecutionReverted:
              $ref: "#/components/examples/errNodeExecutionReverted"
            errPrunedHistory:
              $ref: "#/components/examples/errPrunedHistory"
            errNodeBatchLevel:
              $ref: "#/components/examples/errNodeBatchLevel"
            errUpstreamUnavailable:
              $ref: "#/components/examples/errUpstreamUnavailable"
            errUpstreamTooLarge:
              $ref: "#/components/examples/errUpstreamTooLarge"
            errGatewayOverloaded:
              $ref: "#/components/examples/errGatewayOverloaded"
    NoContent:
      description: >
        Every call in the request is a notification (no `id` member), so the API
        returns no response body. The notifications are still

        rate limited and forwarded, and they are billed once the node has
        processed them normally. A notification that the service itself accepts
        (such as `eth_chainId`) is billed at the CU weight of its method.
        Retryable: not applicable.
    BadRequest:
      description: >
        Produced by the service, empty body: the HTTP message itself is
        malformed. The request is not processed and not billed. When the request
        line or the

        headers cannot be parsed, the HTTP layer of the service answers directly
        (headers too large: 431, URI too long: 414). Invalid chunked

        encoding of the body, or more than 10 s between two reads of the body,
        is answered while the body is read, after authentication and balance
        admission, and the connection is closed afterwards. A request that is
        valid HTTP but not valid JSON-RPC returns

        200 with `-32700` or `-32600`, not 400. Billed: no. Retryable: no, fix
        the request first.
    Unauthorized:
      description: >
        `missing API key` (-32024, `reason = missing_api_key`): `POST
        /v1/{chain}` has neither `x-api-key` nor `Authorization: Bearer`.

        Returned on a known chain, before any key lookup, without reading the
        request body; not billed, does not use rate-limit budget, `id` is
        `null`. 

        `invalid API key` (-32024, `reason = invalid_api_key`): the key is
        unknown, disabled or revoked (one answer for all three, so a client
        cannot tell them apart). Same code family as `missing_api_key`, same
        timing (before the body is read), not billed, `id` is `null`. A
        non-empty `x-api-key` wins over `Authorization`, so a wrong `x-api-key`
        gives this 401 even when the Bearer token is correct.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcErrorResponse"
          examples:
            errMissingApiKey:
              $ref: "#/components/examples/errMissingApiKey"
            errInvalidApiKey:
              $ref: "#/components/examples/errInvalidApiKey"
            errInvalidApiKeyDisabled:
              $ref: "#/components/examples/errInvalidApiKeyDisabled"
            errInvalidApiKeyHeader:
              $ref: "#/components/examples/errInvalidApiKeyHeader"
            errInvalidApiKeyWinsOverBearer:
              $ref: "#/components/examples/errInvalidApiKeyWinsOverBearer"
    PaymentRequired:
      description: >
        Insufficient balance (-32020): the account has no usable allowance left.
        The request is rejected before it is forwarded, is not billed and does
        not use rate-limit budget. `error.data.topup_url` points at the console
        billing page; top up there to continue. When the balance is known,
        `error.data.balance_units` and `error.data.balance_cu` say how much is
        left (negative when overdrawn); they are absent for an account that was
        never funded.

        Billed: no. Retryable: only after the account has been topped up.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcErrorResponse"
          examples:
            paymentRequiredUnfunded:
              $ref: "#/components/examples/paymentRequiredUnfunded"
            paymentRequiredExhausted:
              $ref: "#/components/examples/paymentRequiredExhausted"
    Forbidden:
      description: >
        For these two RPC routes only: OPTIONS returns an empty 204 without
        looking up the chain or key. GET/HEAD first resolve the public chain;
        unknown or non-public chains return 404 unknown_chain. On a known public
        chain, a plain GET returns 405 with Allow: POST and a JSON-RPC -32600
        error whose error.data.reason is method_not_allowed; HEAD returns the
        same status and header with no wire body. A valid WebSocket upgrade
        instead follows separate capability, authentication and admission
        checks; a known chain alone does not guarantee 101. Methods other than
        POST, GET, HEAD and OPTIONS return an empty 403 for both known and
        unknown chains. POST resolves unknown or non-public chains to 404
        unknown_chain before authentication or body processing. Preflight and
        these refusals are not billed.

        A `POST` with a valid key that may not be used any more returns 403 with
        a JSON-RPC error instead: `-32025`, reason `key_expired`

        (the key's expiry time has passed) or `key_cap_exhausted` (its lifetime
        CU cap is used up, `error.data.cu_cap`); not billed, not

        retryable: create a new key in the console.
    NotFoundPathKey:
      description: A JSON error with reason `unknown_chain` for an unknown chain;
        unmatched paths and a trailing slash return 404 with an empty body, not
        billed. On a known chain, a missing key returns 401 `missing_api_key`;
        an unknown, disabled or revoked key returns 401 `invalid_api_key`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcErrorResponse"
          examples:
            notFoundUnknownChain:
              summary: Unknown chain in the path (-32600 unknown chain)
              value:
                jsonrpc: "2.0"
                id: null
                error:
                  code: -32600
                  message: unknown chain
                  data:
                    reason: unknown_chain
                    docs_url: https://docs.blockvectra.com/en/errors/#unknown_chain
                    retryable: false
            notFoundLegacyKeyPath:
              summary: Old-style POST /v1/<key> (the key is taken as a chain slug, so this is
                also an unknown chain and the key is not looked up)
              value:
                jsonrpc: "2.0"
                id: null
                error:
                  code: -32600
                  message: unknown chain
                  data:
                    reason: unknown_chain
                    docs_url: https://docs.blockvectra.com/en/errors/#unknown_chain
                    retryable: false
    PayloadTooLarge:
      description: >
        A request body larger than 2 MiB (2,097,152 bytes) returns 413 with an
        empty body. The request is not processed and not billed.

        Billed: no. Retryable: no, send a smaller body.
    RequestTimeout:
      description: >
        408 with an empty body when no complete response could be returned
        within 35 s of receiving the request headers. The request may already
        have reached the node and be billed as a normal call.

        Billed: possibly. Retryable: with care, because the calls may already
        have been billed. Do not retry calls that change state (such as
        eth_sendRawTransaction) unconditionally.
    TooManyRequests:
      description: "`rate limit exceeded`: retry after the number of seconds in the `Retry-After` header. Each key has a CU rate limit and burst capacity (shown per key in the console Keys table). `request cost <N> CU exceeds burst capacity <M> CU`: a single request exceeds burst capacity; retrying will not succeed, split into smaller requests."
      headers:
        Retry-After:
          description: Seconds until the rate limit bucket has refilled enough to serve
            this request (ceiling, at least 1). Only present on rate limit
            exceeded.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcErrorResponse"
          examples:
            tooManyRequestsRate:
              $ref: "#/components/examples/tooManyRequestsRate"
            tooManyRequestsExceedsBurst:
              $ref: "#/components/examples/tooManyRequestsExceedsBurst"
    ServiceUnavailable:
      description: Billing data is temporarily unavailable; the service temporarily
        rejects requests. This is not a balance issue. Requests are not billed;
        retry after the Retry-After interval.
      headers:
        Retry-After:
          description: Recommended wait time in seconds before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JsonRpcErrorResponse"
    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"
    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"
    AccountOk:
      description: >
        The API key's own balance and limits. Never billed, so it answers 200
        even when the balance is zero or negative. Carries
        `Access-Control-Allow-Origin: *`.
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: "*"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountResponseBody"
          examples:
            accountOk:
              $ref: "#/components/examples/accountOk"
    AccountError:
      description: >
        Not retryable without changing something first: 401 `missing_api_key`
        (no `x-api-key` header) / `invalid_api_key` (unknown, disabled or
        revoked; one identical body for all three), or 403 `key_expired` (a
        valid key past its expiry). None of these is billed; neither is a 200.
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: "*"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountError"
    AccountRetryableError:
      description: >
        Retryable after `Retry-After`: 429 `rate_limited` (over 5
        requests/second for this key id, per service instance) or 503
        `auth_unavailable` (key store stale) / `billing_unavailable` (billing
        data stale or not yet loaded, no balance number). None of these is
        billed; neither is a 200.
      headers:
        Access-Control-Allow-Origin:
          description: CORS allow-list.
          schema:
            type: string
            example: "*"
        Retry-After:
          description: Recommended wait time in seconds before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountError"
  schemas:
    FaucetClaimRequest:
      type: object
      required:
        - address
      additionalProperties: false
      properties:
        address:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: 20-byte EVM address, lowercase or mixed case with a valid EIP-55
            checksum.
    FaucetClaimAccepted:
      type: object
      required:
        - chain
        - chain_id
        - address
        - amount_wei
        - tx_hash
        - next_eligible_at
      additionalProperties: false
      properties:
        chain:
          type: string
          enum:
            - robinhood_testnet
        chain_id:
          type: integer
          enum:
            - 46630
        address:
          type: string
          pattern: ^0x[0-9a-f]{40}$
          description: Normalized lowercase address.
        amount_wei:
          type: string
          pattern: ^[0-9]+$
          enum:
            - "1000000000000000"
          description: Decimal integer wei string; 0.001 test ETH.
        tx_hash:
          type: string
          pattern: ^0x[0-9a-f]{64}$
          description: Stable hash of the accepted transaction; does not imply on-chain
            confirmation.
        next_eligible_at:
          type: string
          format: date-time
          description: Acceptance time plus a rolling 24 hours, in RFC 3339 UTC.
    FaucetError:
      type: object
      description: >
        Faucet error envelope; `error.code` equals `error.data.reason`, and
        message is fixed English text. Every response includes CORS headers for
        any origin and a service-generated `x-bv-request-id`; the body does not
        echo requests or credentials.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - data
          properties:
            code:
              type: string
              enum:
                - invalid_address
                - invalid_request
                - missing_api_key
                - invalid_api_key
                - key_expired
                - not_found
                - request_too_large
                - rate_limited
                - faucet_empty
                - service_unavailable
                - auth_unavailable
                - upstream_unavailable
            message:
              type: string
            data:
              type: object
              required:
                - reason
                - docs_url
                - retryable
                - request_id
              properties:
                reason:
                  type: string
                  description: Equal to error.code.
                docs_url:
                  type: string
                  format: uri
                  description: "`https://docs.blockvectra.com/en/errors/#<reason>`."
                retryable:
                  type: boolean
                  description: True for 429 and 503, false for other errors.
                request_id:
                  type: string
                  description: service-generated request ID, a UUIDv7 in the canonical
                    36-character form; opaque, clients must not parse it.
                field:
                  type: string
                  enum:
                    - /address
                  description: Present for invalid_address.
                scope:
                  type: string
                  enum:
                    - account
                    - address
                    - global
                  description: Scope of a claim-limit 429; omitted for front-door per-key rate
                    limits.
                next_eligible_at:
                  type: string
                  format: date-time
                  description: Next eligible claim time for a claim-limit 429; next UTC day for
                    global limits.
    JsonRpcId:
      description: >
        Call id. A string, a number or `null` is recommended. A missing `id`
        member marks a notification; `"id": null` is not a

        notification. The `id` in a response is always identical to the `id` in
        the request.
      type:
        - string
        - number
        - "null"
    JsonRpcRequest:
      type: object
      required:
        - method
      description: >
        A single call. the service reads only the four members `jsonrpc`, `id`,
        `method` and `params`, and rebuilds the forwarded object from them;

        all other members are dropped. A different letter case or a look-alike
        variant of these four names (such as `METHOD`) makes the call return
        `-32600`.
      properties:
        jsonrpc:
          description: Optional input member. Its value is not validated; the service
            normalizes `jsonrpc` to `"2.0"` in every forwarded call.
        id:
          $ref: "#/components/schemas/JsonRpcId"
        method:
          type: string
          description: Method name. It is allowed or rejected by the method policy in
            Section 5.
          examples:
            - eth_blockNumber
            - eth_call
            - eth_getLogs
            - debug_traceTransaction
        params:
          description: Forwarded to the node unchanged. When it is absent, the forwarded
            object has no `params` either.
          type:
            - array
            - object
    JsonRpcBatchRequest:
      type: array
      minItems: 1
      maxItems: 100
      description: Batch request of 1 to 100 calls. If any element is not an object,
        or lacks a string `method` (and does not contain an ambiguous member
        name), the whole request returns `-32600`.
      items:
        $ref: "#/components/schemas/JsonRpcRequest"
    JsonRpcRequestBody:
      oneOf:
        - $ref: "#/components/schemas/JsonRpcRequest"
        - $ref: "#/components/schemas/JsonRpcBatchRequest"
    JsonRpcErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: Error code, see Section 4.
        message:
          type: string
        data:
          description: Additional data. service errors carry `reason`, `docs_url` and
            `retryable` (and optionally extension fields such as `max` or
            `topup_url`, see Section 4). Additional data returned by the node
            (such as revert data) is passed through unchanged.
          properties:
            reason:
              type: string
              description: Stable snake_case cause code; see the reasons table in Section 4
                for the possible values.
            docs_url:
              type: string
              description: "`<docs base>/errors/#<reason>`, explaining the cause and the fix."
            retryable:
              type: boolean
              description: Whether sending the identical request again later can succeed.
            topup_url:
              type: string
              description: "Only on `insufficient balance` (-32020): the console billing page."
            deposit_address_url:
              type: string
              format: uri
              minLength: 1
              description: "Optional on insufficient-balance 402: the full HTTPS deposit address endpoint, exactly as configured. Absent when not configured; never empty or null. the service only points at this URL and does not serve top-up paths."
            balance_units:
              type: integer
              description: "Only on `insufficient balance` (-32020) when the balance is known: the account's remaining balance units, negative when overdrawn. Absent for an account that was never funded."
            balance_cu:
              type: integer
              description: "Only on `insufficient balance` (-32020) when the balance is known: `balance_units` in CU at the current price (`balance_units * denominator / numerator`, truncated toward zero)."
    JsonRpcSuccessResponse:
      type: object
      required:
        - jsonrpc
        - id
        - result
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          $ref: "#/components/schemas/JsonRpcId"
        result:
          description: The result given by the node. It can be any JSON value, including
            `null`.
    JsonRpcErrorResponse:
      type: object
      required:
        - jsonrpc
        - id
        - error
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          $ref: "#/components/schemas/JsonRpcId"
        error:
          $ref: "#/components/schemas/JsonRpcErrorObject"
    JsonRpcResponse:
      oneOf:
        - $ref: "#/components/schemas/JsonRpcSuccessResponse"
        - $ref: "#/components/schemas/JsonRpcErrorResponse"
    JsonRpcBatchResponse:
      type: array
      description: In request order, one element per call that has an `id`;
        notifications take no slot.
      items:
        $ref: "#/components/schemas/JsonRpcResponse"
    JsonRpcResponseBody:
      oneOf:
        - $ref: "#/components/schemas/JsonRpcResponse"
        - $ref: "#/components/schemas/JsonRpcBatchResponse"
    DataChainsResponse:
      type: object
      description: "Success response of `GET /v1/data/chains` (only the chains that currently offer the Data API, which are the chains with `data: true` in `GET /v1/status`)."
      required:
        - data
      properties:
        data:
          type: array
          description: List of supported chains.
          items:
            $ref: "#/components/schemas/DataChain"
        meta:
          type: object
          description: Metadata object (such as `as_of_block`, `safe_block`,
            `finalized_block`, passed through unchanged).
    DataChain:
      type: object
      description: Configuration and runtime parameters of a chain supported by the
        Data API.
      required:
        - chain
        - chain_slug
        - name
        - chain_id
        - chain_external_id
        - features
        - coverage
        - finality
        - limits
      properties:
        chain:
          type: string
          description: Chain slug used in the `{chain}` path segment, matched exactly in
            lower case.
          example: robinhood_mainnet
        chain_slug:
          type: string
          description: Canonical upper-case chain identifier.
          example: ROBINHOOD_MAINNET
        name:
          type: string
          description: Human-readable display name.
          example: Robinhood Chain
        chain_id:
          type: integer
          format: int64
          description: EIP-155 EVM chain ID.
          example: 4663
        chain_external_id:
          type: string
          description: External chain identifier in CAIP-2 format (`eip155:{chain_id}`).
          example: eip155:4663
        features:
          type: array
          description: Capabilities supported for this chain. An endpoint that is not in
            the list returns 422 `no_coverage`.
          items:
            type: string
          example:
            - blocks
            - transactions
            - address_transactions
            - transfers
            - token_metadata
            - freshness
        coverage:
          $ref: "#/components/schemas/DataChainCoverage"
        finality:
          $ref: "#/components/schemas/DataChainFinality"
        limits:
          $ref: "#/components/schemas/DataChainLimits"
    DataChainCoverage:
      type: object
      description: Data coverage of this chain.
      required:
        - history_mode
        - from_block
        - traces_from_block
      properties:
        history_mode:
          type: string
          enum:
            - full
            - window
          description: "`full` means the full history from the genesis block; `window` means a rolling window (`retention_days`) that keeps only recent data."
        from_block:
          type:
            - integer
            - "null"
          format: int64
          description: First block height of the covered history. This field is always
            present. For a full-history chain (`full`) it is always an integer
            (usually 0); for a rolling-window chain (`window`) it is the current
            lower bound of coverage (it moves forward as partitions expire and
            never moves back). When the underlying data service cannot determine
            the coverage start (it cannot read its storage and the recorded
            value is older than 90 seconds), the field is `null`. `null` occurs
            only on rolling-window chains and means the start is unknown (it
            does not mean 0 and it does not mean full history); while it is
            `null`, clients must not send historical data queries (they return
            503 `unavailable`).
          example: 26000000
        retention_days:
          type: integer
          description: Lower bound of the rolling window in days (only on `window`
            chains). The actual coverage span is never below `retention_days`.
        traces_from_block:
          type:
            - integer
            - "null"
          format: int64
          description: First block height covered by trace data. `null` when the chain
            does not support traces, has no trace data yet, or the value cannot
            be determined.
          example: 72050949
    DataChainFinality:
      type: object
      description: "The chain's finality markers: the node's consensus `safe` and `finalized` blocks, the same values `meta.safe_block` / `meta.finalized_block` carry. Markers only -- they never bound a response (see Finality in the API description). The numbers are per chain and not comparable across chains."
      required:
        - model
        - status
        - safe_block
        - finalized_block
      properties:
        model:
          type: string
          enum:
            - node_tags
          description: "Where the markers come from: the node's `safe` / `finalized` block tags."
        status:
          type: string
          enum:
            - ok
            - stale
            - unavailable
          description: "`ok`: the indexer's heartbeat is at most 120 seconds old (it moves only with a successful read of the node's tags, so a null answer does not refresh it) and neither marker has stood still longer than the chain's configured stall threshold. `stale`: a value is known but the source is behind -- tag reads failing, a marker stalled (for example Ethereum not finalizing), or the markers table unreadable here; the blocks keep their last known values. `unavailable`: no value is known at all (the node has no such tags, or the first read has not happened, or this service never read one); both blocks are `null`."
        safe_block:
          type:
            - integer
            - "null"
          format: int64
          description: The node's `safe` block, `null` only when `status` is
            `unavailable`. Never below `finalized_block`.
        finalized_block:
          type:
            - integer
            - "null"
          format: int64
          description: The node's `finalized` block, `null` only when `status` is
            `unavailable`.
    DataChainLimits:
      type: object
      description: Per-request limits and concurrency limits (passed through by the
        service unchanged).
      required:
        - max_page_size
        - max_window_blocks
        - max_pools_for_token
        - max_batch_addresses
        - max_date_span_days
        - max_concurrent_queries
      properties:
        max_page_size:
          type: integer
          description: Maximum records per page (upper bound of the `limit` parameter).
          example: 500
        max_window_blocks:
          type: integer
          format: int64
          description: Maximum block span (`[from_block, to_block]`) that a window list
            endpoint accepts in one request.
          example: 100000
        max_pools_for_token:
          type: integer
          description: Maximum number of pools that one token query may span.
          example: 200
        max_batch_addresses:
          type: integer
          description: Maximum number of addresses in a batch token request (`POST
            /{chain}/tokens:batch`).
          example: 100
        max_date_span_days:
          type: integer
          description: Maximum span in days of a price history query.
          example: 90
        max_concurrent_queries:
          type: integer
          minimum: 2
          description: "Query concurrency limit advertised by the underlying data service; the service passes this field through unchanged. the service's own query slots are configured separately, per chain, per service instance, shared by all customers. When those slots are full, a request waits up to `acquire_timeout_ms`, then receives 503 `gateway_overloaded` with `Retry-After: 1`. The instance-wide cap, per-account share (default 4 across all keys and chains) and buffered-response byte budget apply independently; this field does not guarantee available slots or describe a per-customer allowance."
          example: 2
    DataMeta:
      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.
        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:
          type:
            - string
            - "null"
          format: date-time
          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\"."
    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.
    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.
    ChainsResponseBody:
      type: object
      required:
        - chains
      properties:
        chains:
          type: array
          items:
            $ref: "#/components/schemas/ChainFacts"
          description: Public chains and their static parameters.
    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.
    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.
    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 `{}`).
    AccountResponseBody:
      type: object
      description: Success response of `GET /v1/account`. Never carries a numeric
        account id, only the key's own `key_id`.
      required:
        - key_id
        - plan
        - balance_units
        - balance_cu
        - balance_as_of_age_ms
        - key
      properties:
        key_id:
          type: string
          description: The API key's own id.
        plan:
          type: string
          enum:
            - free
            - paid
          description: "`free` when the key's account has a free-plan call-rate allowance; `paid` otherwise."
        balance_units:
          type: integer
          description: The settled account balance minus total unsettled account usage
            rounded up to whole units once; hourly settlement rounds down so the
            balance can rise by up to one unit after settlement. May be zero or
            negative; this operation is never billed and never returns 402 for
            it.
        balance_cu:
          type: integer
          description: "`balance_units` in CU at the current price (`balance_units * denominator / numerator`, truncated toward zero)."
        balance_as_of_age_ms:
          type: integer
          description: Milliseconds since the balance above was read from its data source.
        key:
          type: object
          required:
            - cu_per_sec
            - burst_cu
            - cu_cap
            - cu_cap_remaining
            - expires_at
          properties:
            cu_per_sec:
              type: integer
              description: The key's CU-per-second rate limit (its token-bucket refill rate).
            burst_cu:
              type: integer
              description: The key's CU burst capacity (its token-bucket size).
            cu_cap:
              type:
                - integer
                - "null"
              description: The key's lifetime CU cap, or `null` when the key is uncapped.
            cu_cap_remaining:
              type:
                - integer
                - "null"
              description: CU left under `cu_cap` by this service instance's own count, or
                `null` when the key is uncapped. May be zero or negative.
            expires_at:
              type:
                - string
                - "null"
              format: date-time
              description: RFC 3339, or `null` when the key never expires.
    AccountError:
      type: object
      description: Error envelope of `GET /v1/account`.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            data:
              type: object
              description: Every error this operation produces carries `reason`, `docs_url`,
                `retryable` and `request_id` (see Section 4).
              properties:
                reason:
                  type: string
                  description: Stable snake_case cause code; see the reasons table in Section 4
                    for the possible values.
                docs_url:
                  type: string
                  description: "`<docs base>/errors/#<reason>`, explaining the cause and the fix."
                retryable:
                  type: boolean
                  description: Whether sending the identical request again later can succeed.
                request_id:
                  type: string
                  description: Same value as the `x-bv-request-id` response header.
  examples:
    reqBlockNumber:
      summary: Single call to eth_blockNumber
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_blockNumber
        params: []
    reqChainId:
      summary: Single call to eth_chainId
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_chainId
        params: []
    reqBatch:
      summary: Batch of 3 calls
      value:
        - jsonrpc: "2.0"
          id: 1
          method: eth_blockNumber
          params: []
        - jsonrpc: "2.0"
          id: 2
          method: eth_chainId
          params: []
        - jsonrpc: "2.0"
          id: 3
          method: eth_getBalance
          params:
            - "0x1111111111111111111111111111111111111111"
            - latest
    reqEthCall:
      summary: eth_call (latest)
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_call
        params:
          - to: "0x2222222222222222222222222222222222222222"
            data: "0x06fdde03"
          - latest
    reqMixedBatch:
      summary: "Batch: a normal call, a rejected method, an eth_getLogs whose block range is too wide, and one notification"
      value:
        - jsonrpc: "2.0"
          id: 1
          method: eth_blockNumber
          params: []
        - jsonrpc: "2.0"
          id: 2
          method: eth_subscribe
          params:
            - newHeads
        - jsonrpc: "2.0"
          id: 3
          method: eth_getLogs
          params:
            - fromBlock: "0x45a2409"
              toBlock: "0x45a27f1"
        - jsonrpc: "2.0"
          method: eth_chainId
          params: []
    reqNotifications:
      summary: Batch that contains only notifications
      value:
        - jsonrpc: "2.0"
          method: eth_blockNumber
          params: []
        - jsonrpc: "2.0"
          method: eth_chainId
          params: []
    reqSubscribe:
      summary: eth_subscribe over HTTP (use WebSocket for subscriptions)
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_subscribe
        params:
          - newHeads
    reqAmbiguousMember:
      summary: Both a method member and a METHOD member
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_blockNumber
        METHOD: debug_traceCall
        params: []
    reqEmptyBatch:
      summary: Empty array (intentionally does not match the schema)
      value: []
    reqMissingMethod:
      summary: Missing method member (intentionally does not match the schema)
      value:
        jsonrpc: "2.0"
        id: 1
        params: []
    reqBalanceOutsideWindow:
      summary: eth_getBalance at 901 blocks below the chain head
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_getBalance
        params:
          - "0x1111111111111111111111111111111111111111"
          - "0x45a246c"
    reqLogsTooWide:
      summary: eth_getLogs spanning 1001 blocks
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_getLogs
        params:
          - fromBlock: "0x45a2409"
            toBlock: "0x45a27f1"
    reqTraceUnknownTx:
      summary: debug_traceTransaction on a transaction hash that the node cannot find
      value:
        jsonrpc: "2.0"
        id: 1
        method: debug_traceTransaction
        params:
          - "0xabababababababababababababababababababababababababababababababab"
    reqTraceTx:
      summary: debug_traceTransaction
      value:
        jsonrpc: "2.0"
        id: 1
        method: debug_traceTransaction
        params:
          - "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
    reqPrunedBlock:
      summary: A block that is about 14 days old
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_getBlockByNumber
        params:
          - "0x40ddcb1"
          - false
    reqTxReceipt:
      summary: eth_getTransactionReceipt
      value:
        jsonrpc: "2.0"
        id: 1
        method: eth_getTransactionReceipt
        params:
          - "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
    reqBlockNumberBatch3:
      summary: Batch of 3 eth_blockNumber calls
      value:
        - jsonrpc: "2.0"
          id: 1
          method: eth_blockNumber
          params: []
        - jsonrpc: "2.0"
          id: 2
          method: eth_blockNumber
          params: []
        - jsonrpc: "2.0"
          id: 3
          method: eth_blockNumber
          params: []
    reqEthCallBatch3:
      summary: Batch of 3 eth_call calls (the weight of 3 eth_call calls)
      value:
        - jsonrpc: "2.0"
          id: 1
          method: eth_call
          params:
            - to: "0x2222222222222222222222222222222222222222"
              data: "0x06fdde03"
            - latest
        - jsonrpc: "2.0"
          id: 2
          method: eth_call
          params:
            - to: "0x2222222222222222222222222222222222222222"
              data: "0x06fdde03"
            - latest
        - jsonrpc: "2.0"
          id: 3
          method: eth_call
          params:
            - to: "0x2222222222222222222222222222222222222222"
              data: "0x06fdde03"
            - latest
    okSingle:
      summary: Single call succeeds (reqBlockNumber, billed at the weight of
        eth_blockNumber)
      value:
        jsonrpc: "2.0"
        id: 1
        result: "0x45a27f1"
    okBatch:
      summary: "Batch where every call succeeds (reqBatch: eth_blockNumber, eth_chainId and eth_getBalance, each billed at its own weight)"
      value:
        - jsonrpc: "2.0"
          id: 1
          result: "0x45a27f1"
        - jsonrpc: "2.0"
          id: 2
          result: "0x1237"
        - jsonrpc: "2.0"
          id: 3
          result: "0xde0b6b3a7640000"
    okChainId:
      summary: Answer to eth_chainId (reqChainId, billed at the weight of eth_chainId)
      value:
        jsonrpc: "2.0"
        id: 1
        result: "0x1237"
    okMixedBatch:
      summary: "Per-call errors inside a batch (reqMixedBatch: eth_blockNumber and the notification eth_chainId, each billed at its own weight)"
      value:
        - jsonrpc: "2.0"
          id: 1
          result: "0x45a27f1"
        - jsonrpc: "2.0"
          id: 2
          error:
            code: -32601
            message: "method not available: eth_subscribe"
            data:
              reason: method_not_allowed
              docs_url: https://docs.blockvectra.com/en/errors/#method_not_allowed
              retryable: false
        - jsonrpc: "2.0"
          id: 3
          error:
            code: -32602
            message: "eth_getLogs block range too large: max 1000 blocks"
            data:
              reason: logs_range_too_large
              docs_url: https://docs.blockvectra.com/en/errors/#logs_range_too_large
              retryable: false
    errParse:
      summary: Request body is not valid JSON (raw text
        `{"jsonrpc":"2.0","id":1,"method":`)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32700
          message: parse error
          data:
            reason: parse_error
            docs_url: https://docs.blockvectra.com/en/errors/#parse_error
            retryable: false
    errInvalidRequestEmptyBatch:
      summary: Empty batch (reqEmptyBatch)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32600
          message: invalid request
          data:
            reason: invalid_request
            docs_url: https://docs.blockvectra.com/en/errors/#invalid_request
            retryable: false
    errInvalidRequestNoMethod:
      summary: Missing method (reqMissingMethod)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32600
          message: invalid request
          data:
            reason: invalid_request
            docs_url: https://docs.blockvectra.com/en/errors/#invalid_request
            retryable: false
    errBatchTooLarge:
      summary: Batch of more than 100 calls (101 eth_blockNumber calls)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32600
          message: "batch too large: max 100 calls"
          data:
            reason: batch_too_large
            max: 100
            docs_url: https://docs.blockvectra.com/en/errors/#batch_too_large
            retryable: false
    errAmbiguousMember:
      summary: Ambiguous member name (reqAmbiguousMember), rejected per call
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32600
          message: "invalid request: ambiguous member name"
          data:
            reason: invalid_request
            docs_url: https://docs.blockvectra.com/en/errors/#invalid_request
            retryable: false
    errMethodNotAvailable:
      summary: Rejected by the method policy (reqSubscribe)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32601
          message: "method not available: eth_subscribe"
          data:
            reason: method_not_allowed
            docs_url: https://docs.blockvectra.com/en/errors/#method_not_allowed
            retryable: false
    errNodeSyncing:
      summary: Call while the node is not synced (reqBlockNumber)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32010
          message: node is syncing; calls are temporarily unavailable
          data:
            reason: node_syncing
            docs_url: https://docs.blockvectra.com/en/errors/#node_syncing
            retryable: true
    errOutsideStateWindow:
      summary: State call beyond the historical state window (reqBalanceOutsideWindow)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32011
          message: historical state is not available beyond the most recent 900 blocks
          data:
            reason: state_window
            docs_url: https://docs.blockvectra.com/en/errors/#state_window
            retryable: false
    errLogsRangeTooLarge:
      summary: eth_getLogs block range over the limit (reqLogsTooWide)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32602
          message: "eth_getLogs block range too large: max 1000 blocks"
          data:
            reason: logs_range_too_large
            docs_url: https://docs.blockvectra.com/en/errors/#logs_range_too_large
            retryable: false
    errTraceTxNotFound:
      summary: Transaction not found by the trace hash pre-resolution
        (reqTraceUnknownTx)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32000
          message: transaction not found
          data:
            reason: not_found
            docs_url: https://docs.blockvectra.com/en/errors/#not_found
            retryable: false
    errNodeExecutionReverted:
      summary: Execution error returned by the node is passed through and billed
        (reqEthCall, at the weight of eth_call)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32000
          message: execution reverted
    errPrunedHistory:
      summary: "Historical block pruned by the node: 4444 is passed through and not billed (reqPrunedBlock)"
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: 4444
          message: pruned history unavailable
    errNodeBatchLevel:
      summary: Node ends batch processing early (-32003); only the answered calls are
        billed (reqBlockNumberBatch3, one eth_blockNumber)
      value:
        - jsonrpc: "2.0"
          id: 1
          result: "0x45a27f1"
        - jsonrpc: "2.0"
          id: 2
          error:
            code: -32003
            message: response too large
        - jsonrpc: "2.0"
          id: 3
          error:
            code: -32003
            message: response too large
    errUpstreamUnavailable:
      summary: Upstream failure (HTTP 5xx, connection failure, timeout) as a sanitized
        error, not billed (reqTxReceipt)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32603
          message: upstream unavailable
          data:
            reason: upstream_unavailable
            docs_url: https://docs.blockvectra.com/en/errors/#upstream_unavailable
            retryable: true
    errUpstreamTooLarge:
      summary: Upstream response over the size limit, not billed (reqEthCall)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32000
          message: upstream response too large
          data:
            reason: response_too_large
            docs_url: https://docs.blockvectra.com/en/errors/#response_too_large
            retryable: false
    errGatewayOverloaded:
      summary: Upstream concurrency is full, rejected per call, not billed (reqEthCall)
      value:
        jsonrpc: "2.0"
        id: 1
        error:
          code: -32005
          message: service overloaded, retry later
          data:
            reason: overloaded
            docs_url: https://docs.blockvectra.com/en/errors/#overloaded
            retryable: true
    okXApiKey:
      summary: Key in the x-api-key header (reqBlockNumber)
      value:
        jsonrpc: "2.0"
        id: 1
        result: "0x45a27f1"
    okBearer:
      summary: Key in the Authorization Bearer header (reqBlockNumber)
      value:
        jsonrpc: "2.0"
        id: 1
        result: "0x45a27f1"
    okEmptyXApiKeyFallsBackToBearer:
      summary: Empty x-api-key falls back to Bearer (reqBlockNumber)
      value:
        jsonrpc: "2.0"
        id: 1
        result: "0x45a27f1"
    errMissingApiKey:
      summary: POST /v1/{chain} with no key at all (reqBlockNumber; no key segment in
        the path, and no x-api-key / Authorization header)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32024
          message: "missing API key: send it in the request path (/v1/{chain}/<api_key>) or in the x-api-key header"
          data:
            reason: missing_api_key
            docs_url: https://docs.blockvectra.com/en/errors/#missing_api_key
            retryable: false
    errInvalidApiKey:
      summary: Unknown key in the path on a known chain
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32024
          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
    errInvalidApiKeyDisabled:
      summary: Disabled key on a known chain (the same answer as an unknown key)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32024
          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
    errInvalidApiKeyHeader:
      summary: Unknown x-api-key
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32024
          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
    errInvalidApiKeyWinsOverBearer:
      summary: Wrong x-api-key with a correct Bearer token still gives 401 (x-api-key
        wins)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32024
          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
    paymentRequiredUnfunded:
      summary: Account balance is 0 (reqBlockNumber)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32020
          message: insufficient balance
          data:
            reason: balance_exhausted
            docs_url: https://docs.blockvectra.com/en/errors/#balance_exhausted
            retryable: false
            topup_url: https://console.blockvectra.com/billing
    paymentRequiredExhausted:
      summary: Balance used up (the account spends one reqBlockNumber, after which the
        same request is rejected; the balance fields show what is left)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32020
          message: insufficient balance
          data:
            reason: balance_exhausted
            docs_url: https://docs.blockvectra.com/en/errors/#balance_exhausted
            retryable: false
            topup_url: https://console.blockvectra.com/billing
            balance_units: 0
            balance_cu: 0
    tooManyRequestsRate:
      summary: "Rate limit exceeded: not enough CU left in your key's bucket; retry after the Retry-After seconds."
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32005
          message: rate limit exceeded
          data:
            reason: key_rate_limit
            docs_url: https://docs.blockvectra.com/en/errors/#key_rate_limit
            retryable: true
    tooManyRequestsExceedsBurst:
      summary: A single request (3 eth_call calls) whose CU cost exceeds the burst
        capacity of the key (reqEthCallBatch3)
      value:
        jsonrpc: "2.0"
        id: null
        error:
          code: -32022
          message: request cost <N> CU exceeds burst capacity 40 CU
          data:
            reason: request_exceeds_burst
            docs_url: https://docs.blockvectra.com/en/errors/#request_exceeds_burst
            retryable: false
    statusOk:
      summary: Public service status response
      value:
        checked_at: 2026-09-28T12:00:00Z
        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-28T11:59:58Z
              lag_seconds: 2
    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
    accountOk:
      summary: Account balance and limits response
      value:
        key_id: k_9f2a
        plan: paid
        balance_units: 182345
        balance_cu: 182345000
        balance_as_of_age_ms: 1200
        key:
          cu_per_sec: 50
          burst_cu: 500
          cu_cap: null
          cu_cap_remaining: null
          expires_at: null
x-rpc-methods:
  tracers:
    allowed:
      - callTracer
      - flatCallTracer
      - prestateTracer
      - 4byteTracer
      - noopTracer
    omitted: default struct logger
    max_timeout_secs: 30
  cu:
    weights: Per-method CU weights are published by GET /v1/plans; unlisted methods
      use the '*' entry. debug_trace* and trace_* are ordinary prefix rows in
      that table, resolved by the same rule as every other method.
    resolution: exact > longest prefix (pattern ending in *) > the '*' row
    resolution_examples:
      eth_call: exact match
      debug_traceTransaction: matches the debug_trace* prefix rule
      web3_sha3: falls back to the '*' row
  price:
    description: Prices are defined by the plan and published by GET /v1/plans (the
      pricing object and the per-method CU weights). No price is hard-coded in
      this document.
    cu_per_unit: Defined by the pricing object of GET /v1/plans.
    settlement: The CU consumed by an account in each hourly period is converted to
      billing units, rounded down, with the CU price from GET /v1/plans.
    admission: A request is blocked when the account balance minus the unsettled CU
      converted to billing units (rounded up) is zero or less.
x-rpc-errors:
  - code: -32700
    source: service
    http: 200
    message: parse error
    reason: parse_error
    billed: false
  - code: -32600
    source: service
    http: 200
    message: invalid request
    reason: invalid_request
    billed: false
  - code: -32600
    source: service
    http: 200
    message: "batch too large: max <N> calls"
    reason: batch_too_large (+max)
    billed: false
  - code: -32600
    source: service
    http: 200
    message: "invalid request: ambiguous member name"
    reason: invalid_request
    billed: false
  - code: -32601
    source: service
    http: 200
    message: "method not available: <method>"
    reason: method_not_allowed
    billed: false
  - code: -32600
    source: service
    http: 404
    message: unknown chain
    reason: unknown_chain
    billed: false
  - code: -32602
    source: service
    http: 200
    message: "eth_getLogs block range too large: max <N> blocks"
    reason: logs_range_too_large
    billed: false
  - code: -32602
    source: service
    http: 200
    message: tracer not allowed
    reason: invalid_params
    billed: false
  - code: -32602
    source: service
    http: 200
    message: trace timeout not allowed
    reason: invalid_params
    billed: false
  - code: -32010
    source: service
    http: 200
    message: node is syncing; calls are temporarily unavailable
    reason: node_syncing
    billed: false
  - code: -32011
    source: service
    http: 200
    message: historical state is not available beyond the most recent <N> blocks
    reason: state_window
    billed: false
  - code: -32011
    source: service
    http: 200
    message: requested history is not completely indexed
    reason: range_not_indexed
    billed: false
  - code: -32011
    source: service
    http: 200
    message: requested history is not ready
    reason: history_not_ready
    billed: false
  - code: -32000
    source: service
    http: 200
    message: transaction not found
    reason: not_found
    billed: false
  - code: -32000
    source: service
    http: 200
    message: block not found
    reason: not_found
    billed: false
  - code: -32000
    source: service
    http: 200
    message: upstream response too large
    reason: response_too_large
    billed: false
  - code: -32005
    source: service
    http: 200
    message: service overloaded, retry later
    reason: overloaded
    billed: false
  - code: -32005
    source: service
    http: 503
    message: service overloaded, retry later
    reason: overloaded
    billed: false
  - code: -32005
    source: service
    http: 429
    message: rate limit exceeded
    reason: key_rate_limit | free_plan_call_limit | concurrency_limit
    billed: false
  - code: -32022
    source: service
    http: 429
    message: request cost <N> CU exceeds burst capacity <M> CU
    reason: request_exceeds_burst
    billed: false
  - code: -32022
    source: service
    http: 429
    message: request has <N> calls, exceeding the free-plan limit of <M> calls per
      second
    reason: free_plan_batch_too_large (+max)
    billed: false
  - code: -32603
    source: service
    http: 200
    message: upstream unavailable
    reason: upstream_unavailable
    billed: false
  - code: -32603
    source: service
    http: 200
    message: no response from upstream
    reason: upstream_unavailable
    billed: false
  - code: -32603
    source: service
    http: 200
    message: malformed upstream response
    reason: upstream_unavailable
    billed: false
  - code: -32603
    source: service
    http: 200
    message: unexpected service error
    reason: internal_error
    billed: false
  - code: -32020
    source: service
    http: 402
    message: insufficient balance
    reason: balance_exhausted | free_grant_exhausted
    billed: false
  - code: -32024
    source: service
    http: 401
    message: "missing API key: send it in the request path (/v1/{chain}/<api_key>) or in the x-api-key header"
    reason: missing_api_key
    billed: false
  - code: -32024
    source: service
    http: 401
    message: "invalid API key: it is unknown, disabled or revoked; check the key in the console"
    reason: invalid_api_key
    billed: false
  - code: -32025
    source: service
    http: 403
    message: API key expired; create a new key in the console
    reason: key_expired
    billed: false
  - code: -32025
    source: service
    http: 403
    message: API key CU cap exhausted; create a new key in the console
    reason: key_cap_exhausted (+cu_cap)
    billed: false
  - code: -32021
    source: service
    http: 503
    message: authentication data temporarily unavailable
    reason: auth_unavailable
    billed: false
  - code: -32021
    source: service
    http: 503
    message: billing data temporarily unavailable
    reason: billing_unavailable
    billed: false
  - code: 4444
    source: node
    http: 200
    message: pruned history unavailable
    billed: false
  - code: -32000
    source: node
    http: 200
    message: historical state ... is not available
    billed: false
  - code: -32000
    source: node
    http: 200
    message: old data not available due to pruning...
    billed: false
  - code: -32000
    source: node
    http: 200
    message: missing trie node ...
    billed: false
  - code: -32002
    source: node
    http: 200
    message: <node message>
    billed: false
  - code: -32003
    source: node
    http: 200
    message: <node message>
    billed: false
  - code: -32601
    source: node
    http: 200
    message: <node message>
    billed: false
  - code: -32603
    source: node
    http: 200
    message: <node message>
    billed: false
  - code: -32600
    source: node
    http: 200
    message: <node message>
    billed: false
  - code: "*"
    source: node
    http: 200
    message: <node message>
    billed: true
  - code: -32601
    source: service
    http: 200
    message: method is not available on the public endpoint
    reason: method_not_public
    billed: false
  - code: -32005
    source: service
    http: 429
    message: public request rate limit exceeded
    reason: public_rate_limit
    billed: false
  - code: -32005
    source: service
    http: 429
    message: public chain pool is busy
    reason: public_pool_busy
    billed: false
