Base RPC URL: keyless access, curl and viem examples

Start with the Base mainnet public RPC URL below to read the chain ID without an API key. Check supported methods and per-IP limits on the Base chain page; use a key for methods outside public.methods that the chain allows.

curl -sS "https://api.blockvectra.com/v1/base_mainnet/public" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Network information and endpoints

Every request to Base identifies its target network explicitly in the URL path using the slug base_mainnet. JSON-RPC supports both path-based key authentication and request header authentication (x-api-key).

Direct curl and viem examples

You can make JSON-RPC calls directly using curl or web3 client libraries such as viem. Set your API key in the BLOCKVECTRA_API_KEY environment variable:

curl -s "https://api.blockvectra.com/v1/base_mainnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Response structure

Responses adhere to the JSON-RPC 2.0 specification:

• Success: Returns an object containing jsonrpc: "2.0", matching integer id, and hexadecimal-encoded result (eth_chainId returns the hex-encoded chain ID; eth_blockNumber returns the latest block height).
• Disallowed methods: Requesting a method outside the network's allowed methods returns JSON-RPC error code -32601 (method not available, not billed).
• Out-of-window queries: Historical state requests earlier than the state retention window return JSON-RPC error code -32011 (not billed).
• Missing API key: Omitting the key returns HTTP 401 with JSON-RPC error code -32024 (missing_api_key, not billed).
• Invalid parameters: Malformed request parameters return JSON-RPC error code -32602 (not billed).

Capability and method policy

Live values: GET /v1/chains (methods, max_logs_block_range, state_window_blocks).

Blockchain Data API

Live values: GET /v1/chains (data).

Find direct calls to a contract, then fetch receipts

To list transactions sent directly to your contract in a fixed block range and read their receipts, page through the address transactions endpoint, then call eth_getTransactionReceipt for each returned hash. Both bounds are inclusive, so a 200-block range is TO_BLOCK = FROM_BLOCK + 199.

export CONTRACT=0x...   # your contract address
export FROM_BLOCK=...   # range start (inclusive)
export TO_BLOCK=...     # range end (inclusive)

curl -sS "https://api.blockvectra.com/v1/data/base_mainnet/addresses/$CONTRACT/transactions?from_block=$FROM_BLOCK&to_block=$TO_BLOCK&direction=to&limit=500" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

1. Each item in data has a hash. If the top-level next_cursor is present, repeat the request with the same query plus &cursor=<next_cursor>, passing the cursor back unchanged. Stop when next_cursor is absent. A page can hold fewer than limit rows, or none, while next_cursor is still present.
2. Check meta.coverage on every page. partial means the range was clamped or starts before this dataset's indexed start, so the list does not cover the whole range. An empty list is not proof that the range had no calls.
3. Fetch each receipt from the same chain with the same key. hash already starts with 0x; put the complete value from data into TX_HASH unchanged, without adding another 0x:

curl -sS "https://api.blockvectra.com/v1/base_mainnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$TX_HASH\"]}"

Handle errors by layer:

• Data API: 409 not_indexed_yet means the range is above the indexed head, so retry later or add clamp=true, which truncates to_block down to the indexed head and returns meta.coverage = "partial" (a clamped result no longer covers your original fixed range; if from_block itself is above the indexed head, clamp=true still returns 409); 409 window_too_large means the range exceeds 100,000 blocks; 422 no_coverage means the range is outside the dataset; 503 unavailable carries Retry-After, so wait at least that many seconds and retry with the same cursor.
• JSON-RPC: an HTTP error or an error object in the body is a failed call. "result": null means no receipt was returned for that hash, not success; retry later or check the hash. A non-null receipt does not mean the transaction succeeded: status 0x1 is success and 0x0 means it reverted.

This lists only top-level transactions whose to is the contract. It does not include events, internal calls or transactions that reach the contract through another contract. Supported methods and ranges come from GET /v1/chains and the actual response. For pagination and event queries, see eth_getLogs vs Token Transfers API.

Getting started and API keys

• Web console: Sign up via Ethereum wallet signature, and generate an API key in the Console. See the Quickstart guide for setup details.
• Programmatic sign-up: Autonomous AI agents, automated scripts, and CI pipelines can sign in and provision API keys using Ethereum wallet signatures (EIP-191) without a browser. Follow the Programmatic sign-up guide.
• AI agents: Autonomous AI agents can discover Base capabilities using the official Model Context Protocol (MCP) server. See Connecting AI Agents to BlockVectra.
• Upgrading limits: After topping up, the account-wide calls-per-second limit is removed; each key remains subject to Compute Unit (CU) rate and burst limits. For current rates and billing units, see the Pricing page.

Related guides and resources

• Base developer documentation: For network specifications, gas mechanics, and contracts on Base, see the official Base documentation.
• Wallet custom RPC: Configure custom RPC endpoints for Base in MetaMask and Rabby using the Wallet Custom RPC guide.
• Transaction simulation: Test transaction execution and evaluate state changes before broadcasting using eth_simulateV1 in the Simulate Transactions guide.

Next steps

• Browse the datasets directory to see every dataset BlockVectra indexes.
• See the free plan and pricing to check what your account includes.
• Log in to the console to create an API key.