JSON-RPC

OverviewCopy Anchor Link

JSON-RPC 2.0 access on every supported chain is metered through the BlockVectra gateway. All requests are counted in Computation Units (CU) and rate-limited per key.

• Endpoint: POST /v1/{chain}/{api_key} (key in the path) or POST /v1/{chain} (key in a header). For Robinhood Chain, {chain} is robinhood_mainnet: https://dev-api.blockvectra.network/v1/robinhood_mainnet. The same API key works on every supported chain
• Protocol: HTTP POST, single call or batch (max 100 calls)
• Metering: A request's total CU cost counts against your key's burst capacity as soon as it arrives. Every accepted call that gets a response is charged at the method's published CU weight; the error-code table lists the cases that are not billed (see Error Codes). Billing is settled hourly (rounded down to whole units, remainder carries over, executed ~15 minutes after the period ends)
• Availability: Available methods vary by chain. On Robinhood Chain: eth_*, net_*, web3_*, debug_trace* (with exceptions; see below). For other chains, see Supported Chains.
• Ethereum (Beta): its own method list and about 36 days of recent data — see Supported Chains → Ethereum.

IntegrationCopy Anchor Link

1. Get an API KeyCopy Anchor Link

See Quickstart → Get an API key.

2. Call JSON-RPCCopy Anchor Link

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet/$BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Key passing (priority order):

• URL path: POST /v1/{chain}/{api_key}
• Header on POST /v1/{chain}: x-api-key: {api_key} (overrides Bearer if non-empty)
• Header on POST /v1/{chain}: Authorization: Bearer {api_key}

3. Handle CU CostsCopy Anchor Link

Every method carries a CU (Computation Unit) weight; the cost of a request is the sum of the weights of all calls it contains. See the CU weight table below for per-method weights and default values, and the Billed column of the error codes table for which error conditions are billed. Usage is charged per account per hourly period, rounded down to whole billing units (1 unit = 1000 CU), with the remainder carrying over to the next period (across periods the total charged is floor(total CU / 1000)); settlement runs about 15 minutes after the period ends (for example: 508 CU carried over + 2557 CU consumed = 3065 CU charges 3 billing units, with 65 CU carried over).

Common CallsCopy Anchor Link

Worked examples for common calls.

Query logs (eth_getLogs)Copy Anchor Link

Filter a contract's logs over a recent block range — here, the ERC-20 Transfer event (topic 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef). See the CU Metering Rules table below for eth_getLogs's current CU weight; the gateway rejects any range wider than that chain's eth_getLogs span limit. On Robinhood Chain the limit is 1000 blocks (-32602 eth_getLogs block range too large: max 1000 blocks); for other chains, see Supported Chains.

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a2609",
      "address": "0x1111111111111111111111111111111111111111",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }],
    "id": 1
  }'

Trace a transaction (debug_traceTransaction)Copy Anchor Link

Trace a transaction's internal calls with the callTracer. See the CU Metering Rules table below for debug_trace*'s current CU weight. Like the other state-reading methods, it's rejected once the target block falls outside that chain's recent-state window (-32011). On Robinhood Chain the window is the chain head minus 900 blocks; for other chains, see Supported Chains. On chains that provide traces, use the Data API for historical traces.

Note: The transaction must be within the chain's recent-state window (on Robinhood Chain about the last 900 blocks, i.e. only minutes); older transactions return -32011 (historical state is not available beyond the most recent 900 blocks).

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": ["0xYOUR_TRANSACTION_HASH", {"tracer": "callTracer"}],
    "id": 1
  }'

Batch several callsCopy Anchor Link

Send several calls in a single request — up to the batch limit noted above (max 100 calls per request). This example reads the block number, chain ID, and gas price in one round trip.

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1},
    {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2},
    {"jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3}
  ]'

If the gateway rejects the whole batch instead — insufficient balance, rate limiting, burst capacity, or more than 100 calls (see the Error Codes table below) — it returns a single JSON-RPC error object instead of an array; viem's batch: true mode then surfaces this as an opaque UnknownRpcError, so retry a single call to see the actual error.

CU Metering RulesCopy Anchor Link

Method PolicyCopy Anchor Link

Available methods vary by chain; each chain's list is shown below, and Supported Chains covers the rest. Only methods matching an allowed name or pattern are reachable; a handful of methods are explicitly blocked even though they match one (they return -32601 method not available).

Limits:

• Batch: max 100 calls per request; also limited by the key's CU burst, see below.
• Request body: max 2 MiB
• CU burst: each API key has a CU bucket (cu_per_sec refill, burst_cu capacity — defaults are 100 CU/s and burst 400 CU; shown per key in the console Keys table). A single request — including a whole JSON-RPC batch — whose total CU exceeds the key's burst capacity is rejected with -32022 request_exceeds_burst (request cost <N> CU exceeds burst capacity <M> CU); split it into smaller batches.

Error CodesCopy Anchor Link

Full OpenAPI ReferenceCopy Anchor Link

See the Full OpenAPI reference for the complete machine-readable specification with all method signatures, request and response schemas, and parameter details rendered interactively.