Starkscan RPC

Starkscan RPC is an authenticated Starknet JSON-RPC beta. Use a standard Starknet JSON-RPC client for the methods in the published HTTP contract, with one API key that also works across the Starkscan REST API and CLI.

Connect

Use one of these two header-authenticated endpoints. They reach the same public RPC contract; choose the first form for a new hosted integration.

Do not send an external client to https://starkscan.co/v1/...: that same-origin path is reserved for the explorer application. Replace SN_MAIN with the chain you intend to call.

curl "https://api.starkscan.co/v1/SN_MAIN/rpc" \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"starknet_blockNumber","params":[]}'

Starknet uses the starknet_ method namespace — not eth_, and it does not run the EVM. See the method reference for the full set.

X-Api-Key is accepted as an alias for X-Starkscan-Api-Key. Send the key in one header only: two different keys are rejected with HTTP 400.

Versions and paths

Starkscan serves Starknet JSON-RPC 0.10 only. It has no 0.9 or older translation layer, so a client pinned to RPC 0.9 must move to a client that speaks 0.10 before it switches to Starkscan. The gateway answers on the header-auth URLs above and on the node-URL form https://starkscan.co/rpc/v0_10/{chain}/{token}.

A JSON-RPC POST to any other RPC path gets HTTP 404 and a JSON-RPC error, not a web page. That covers another version such as /rpc/v0_9/SN_MAIN/<key>, a path without the version such as /rpc/SN_MAIN/<key>, and a mixed shape such as /api/rpc/v0_10/SN_MAIN/<key>. The error is code -32601 with error.data.code unsupported_rpc_version or unknown_rpc_path, and its data names the supported paths and version. It never repeats the path, so a key in a mistyped URL is not echoed back. See RPC errors.

Why Starkscan RPC

• Standard JSON-RPC 2.0. Send single requests or batches with X-Starkscan-Api-Key; use the URL-token form only for clients that cannot attach a header.
• One key, three surfaces. The same key authenticates RPC, the REST API, and the CLI — one secret to rotate, one budget, one support surface.
• Bounded, explicit scope. The gateway forwards the documented allowlist and fails closed for methods outside it. Read the live capability document before you depend on optional write or trace access.
• Structured failure handling. RPC authentication and handler failures use JSON-RPC errors, including non-2xx authentication responses; other REST routes retain their REST envelope. See RPC errors.
• Useful response metadata. Capture X-Request-Id, X-Starkscan-Rpc-Class, and X-Ratelimit-* when returned. They identify the quota class, support request, and backoff boundary for a call.

Discover the live contract

Fetch the authenticated capability document before enabling an optional feature, especially signed writes. Its rpcProvider section reports the host-appropriate endpoint shape, accepted block tags, batch limit, quota classes, the declared public spec contract and minimum backend floor, and the current write-beta state. For proofs, read rpcProvider.storageProofBeta before assuming an archive horizon or a state_diff_commitment response field. Every accepted auth form is listed: rpcProvider.acceptedAuthHeaders names both key headers, and rpcProvider.urlTokenEndpoint.nodeUrlPath gives the node-URL path for the deployment's chain, for example /rpc/v0_10/SN_MAIN/{apiKey}, when the deployment serves the node-URL form. The path is host-relative: prefix the origin that served the capabilities document, so the key always goes to that deployment. The document never contains a key.

curl "https://api.starkscan.co/v1/meta/capabilities" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY"

starknet_specVersion returns rpcProvider.publicSpecVersion, the stable gateway compatibility contract, rather than a randomly selected backend's raw version. Backend implementations may be newer or prerelease, but active health requires them to meet rpcProvider.minimumSpecVersion and the gateway's fixed identity and call probes. The raw backend version remains operator evidence; it is not the client contract.

What it is not (yet)

We are explicit about scope so you never guess:

Keep an existing Starknet RPC provider for anything in the bottom two rows until Starkscan documents and proves it for your workload.

Each selected trace response is capped at 16 MiB. An oversized result fails closed with error.data.code=trace_response_too_large; it is never truncated into a response that could be mistaken for a complete execution trace.

The optional per-trace state_diff is omitted deliberately because the heterogeneous upstream pool does not return it consistently. Use starknet_getStateUpdate for canonical state changes. If an upstream omits or malforms a field required by the Starknet trace schema, Starkscan fails closed with trace_response_incomplete instead of returning an auditor-unsafe trace.

Quickstart

1. Get a key — see Get an API key. The keys page shows both the node-URL and header forms.

2a. Header auth (preferred for servers):

export STARKSCAN_RPC_API_URL="https://api.starkscan.co/v1/SN_MAIN/rpc"
export STARKSCAN_API_KEY="<your 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_chainId","params":[]}'

2b. Node URL (for nodeUrl-only clients):

export STARKSCAN_RPC_NODE_URL="https://starkscan.co/rpc/v0_10/SN_MAIN/<starkscan_api_key>"

import { RpcProvider } from "starknet";
const provider = new RpcProvider({ nodeUrl: process.env.STARKSCAN_RPC_NODE_URL });
await provider.getBlockNumber();

Treat the node URL as a secret — it embeds your key. Never paste it into chats, tickets, screenshots, or logs; rotate the key if it leaks.

Batch

Batch JSON-RPC is supported up to 50 items per request (array POST → array response). Each sub-call is billed and classified individually. The aggregate serialized response is capped at 16 MiB. Over either cap you get a clean typed error, not a partial success:

{"jsonrpc":"2.0","id":null,
 "error":{"code":-32600,
   "data":{"code":"batch_too_large","maxItems":50,"receivedItems":51,"requestId":"mzk-…"}}}

Chunk larger workloads (e.g. N tokens × M wallets) into no more than 50 items, and split batches again if their results can approach the 16 MiB aggregate cap.

Choosing a surface

Use RPC for starknet.js / node-URL compatibility. Prefer another Starkscan surface when it fits better:

Reference

• Method reference — every method, params, and a representative result or error shape, grouped by rate-limit class.
• RPC errors — the full JSON-RPC + envelope error contract.
• Rate limits — the per-class budgets and headers.
• WebSocket beta — subscriptions (beta on mainnet, pending its 24-hour soak), with header and browser URL-token connection forms.

For finality, rely on Starknet's native status / finality_status fields and on the guarantees documented by the provider you choose.

Related

• Get an API key · API keys page
• REST API guide · Agent HTTP quickstart