BlockVectra Faucet API

openapi: 3.2.0
info:
  title: BlockVectra JSON-RPC Faucet 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: 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-05 08:00:00+00:00
        '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'
components:
  schemas:
    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.
    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.
    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.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key. When it is not empty it takes precedence over `Authorization`. Leading and trailing whitespace is trimmed.
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <api_key>`. Only the prefixes `Bearer ` and `bearer ` are accepted. Used only when `x-api-key` is missing or empty.'
x-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