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, MCP, 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.

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, four surfaces. The same key authenticates RPC, the REST API, hosted MCP, 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.

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 (named-client beta).

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