Starkscan RPC

Use Starkscan RPC when your wallet, script, backend, or agent expects Starknet JSON-RPC method names instead of the REST routes in the API guide. The same Starkscan API key works for REST and RPC. The UI shows both forms when you create a key.

Copy this if your app wants one RPC URL

Most wallets, CLIs, and provider fields expect a single node URL. Use this compatibility shape:

https://starkscan.co/rpc/v0_10/SN_MAIN/<starkscan_api_key>

Example:

export STARKSCAN_RPC_NODE_URL="https://starkscan.co/rpc/v0_10/SN_MAIN/$STARKSCAN_API_KEY"

For preview or self-hosted deployments, replace starkscan.co with that deployment's app host before sharing the URL with a nodeUrl client.

Then paste STARKSCAN_RPC_NODE_URL wherever the software asks for a Starknet RPC URL or node URL.

Treat the full URL as a secret. It contains your Starkscan API key. Do not paste it into Slack, tickets, screenshots, PR comments, source code, or public logs. Rotate the key if the full URL leaks.

Preferred server shape

If your backend can send headers, prefer header auth. It keeps the secret out of the URL path and is easier to redact in logs.

Literal header shape: X-Starkscan-Api-Key: <starkscan_api_key>.

export STARKSCAN_RPC_API_URL="https://api.starkscan.co/v1/SN_MAIN/rpc"
export STARKSCAN_API_KEY="<your Starkscan API key>"

curl "$STARKSCAN_RPC_API_URL" \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"starknet_blockNumber","params":[]}'

Batch requests

Batches are supported up to 25 JSON-RPC items per request. Keep batches bounded, and log the same request IDs and rate-limit headers you log for single calls.

curl "$STARKSCAN_RPC_API_URL" \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  --data '[
    {"jsonrpc":"2.0","id":1,"method":"starknet_chainId","params":[]},
    {"jsonrpc":"2.0","id":2,"method":"starknet_blockNumber","params":[]}
  ]'

starknet.js

For libraries that only accept nodeUrl, use the compatibility URL:

import { RpcProvider } from "starknet";

const provider = new RpcProvider({
  nodeUrl: process.env.STARKSCAN_RPC_NODE_URL,
});

const blockNumber = await provider.getBlockNumber();
console.log(blockNumber);

If your runtime supports custom headers, use the preferred server endpoint and attach X-Starkscan-Api-Key with your key.

What is enabled

For recognized RPC methods, the HTTP RPC gateway attaches X-Starkscan-Rpc-Class to classified responses. Malformed requests can fail before classification; when the header is present, treat it as the operational source for backoff and support reports.

starknet_blockHashAndNumber is the method name. Do not call starknet_getBlockHashAndNumber.

starknet_getStorageProof is a bounded proof beta method. Prefer a concrete block_number or block_hash for reproducible proofs. latest is accepted for live reads, but pending and pre_confirmed are rejected. Keep requests small: at most 8 class_hashes, 8 contract_addresses, 8 contracts_storage_keys entries, 16 storage keys per contract, and 32 total proof targets. The 32-target total is class_hashes + contract_addresses + all individual storage_keys; contracts_storage_keys entries are capped separately. Responses above the Starkscan proof payload cap fail with storage_proof_response_too_large; split the request and retry without blind loops.

starknet_getCompiledCasm is also a large-payload method. Starkscan caps the serialized JSON-RPC item at 4 MiB and returns compiled_casm_response_too_large when a compiled CASM payload exceeds that bound.

Event reads over RPC

starknet_getEvents is supported, but it is still a bounded JSON-RPC method, not a full-history export job.

• Use numeric from_block and to_block for reproducible windows.
• Keep chunk_size <= 1000.
• Keep the block span at or below 10,000.
• Prefer the named wrapper shape in generated clients: params: {"filter":{"from_block":{"block_number":N},"to_block":{"block_number":N},"chunk_size":100}}.
• The direct filter shape is also accepted: params: {"from_block":{"block_number":N},"to_block":{"block_number":N},"chunk_size":100}.
• Do not mix a nested filter object with top-level filter keys.

For indexed full-history event search, prefer REST GET /v1/{chain}/events or GET /v1/{chain}/contract/{address}/events with selective filters and nextCursor pagination. Those routes are built for indexed event search; RPC getEvents is better for clients that must keep JSON-RPC method names.

When to choose REST instead

Use REST instead of RPC when Starkscan already exposes a certified or indexed route for the data model you need:

Current boundaries

Starkscan RPC requires an authenticated beta key. It does not provide no-key public RPC, broad tracing, unrestricted archive/full-history parity, or an unrestricted public write relay.

WebSocket subscriptions are not part of the default HTTP nodeUrl contract. A separate GET /v1/{chain}/rpc/ws WSS proxy route exists for beta certification, but keep your existing Starknet RPC provider for WebSockets and other unsupported surfaces until Starkscan explicitly enrolls your client and proves those routes for your workload.

Smoke checklist

Before switching a wallet, backend, or agent to Starkscan RPC, verify:

• missing or bad auth returns a clean rejection
• starknet_chainId, starknet_specVersion, starknet_blockNumber, and starknet_blockHashAndNumber return results
• a known-good starknet_call returns the expected value
• a bounded starknet_getEvents request returns an event page
• bounded starknet_getStorageProof, starknet_getMessagesStatus, and starknet_getCompiledCasm probes exercise their documented success or bounded-error contracts
• batch requests stay under the 25-item cap
• malformed write probes do not succeed and return rpc_write evidence
• trace and subscription probes fail closed with rpc_trace or rpc_ws

Error-report contract

When reporting a failing RPC call, include:

• HTTP status
• JSON-RPC result or error
• X-Request-Id
• X-Starkscan-Rpc-Class
• X-Ratelimit-* headers
• whether you used header auth or the URL-token node URL

Do not include the full API key or the full URL-token RPC URL in the report.

Related docs

• Get your first API key
• API keys page
• API guide
• Agent HTTP quickstart
• Launch matrix