Concepts
Terms you will see across Starkscan docs—URLs, auth, pagination, and API tiers.
Concepts
Short definitions shared by the Quickstart, REST guide, and Build pages.
New to the API? Start with Get your first API key. For the details behind these terms see Authentication, Base URLs and chains, and Pagination and cursors.
Host and path
| Term | Meaning |
|---|---|
STARKSCAN_BASE_URL | Optional override for preview or self-hosted API roots: API-host roots or app-host /api bases. Hosted clients default to https://api.starkscan.co when this is unset. |
STARKSCAN_RPC_URL | Full Starkscan JSON-RPC provider URL shape. Use https://starkscan.co/rpc/v0_10/SN_MAIN/<starkscan_api_key> when a client only accepts a node URL, or https://api.starkscan.co/v1/SN_MAIN/rpc with header auth when a client can attach X-Starkscan-Api-Key. For preview or self-hosted deployments, replace the hosted app/API host with your deployment's host before copying these examples. See Starkscan RPC. |
/v1/{chain} | Chain segment in the path. SN_MAIN is Starknet mainnet. Full example: https://api.starkscan.co/v1/SN_MAIN/status. |
Same-origin /v1/* | Inside the web app, the browser may call /v1/... via proxy. Integrators following these docs use the API host /v1/...; app-host /api/v1/... remains compatibility. |
Auth
| Term | Meaning |
|---|---|
X-Starkscan-Api-Key | Header you send on every API request. No Bearer prefix—just the key value for the key issued to your integration. |
| 401 | Key missing or not accepted. Fix credentials before retrying. |
| 403 | Key valid but route or tier not allowed (common on batch utility routes). |
| 429 | Rate limit reached for the current route class. Honor Retry-After before retrying. |
Lists and data shape
| Term | Meaning |
|---|---|
| Cursor pagination | List responses use items and often nextCursor. Pass the cursor back to get the next page. Offsets are not the default model. |
limit | Cap on how many rows one response returns. Keep it modest on hosted APIs. |
Route tiers
| Tier | Meaning |
|---|---|
| Official public API | Default documented contract in Scalar and starkscan-openapi.yaml. Start here. |
| Advanced utilities | Supported batch helpers (e.g. tx previews, tx detail hydration, address summaries). Often need a broader key. See Advanced utilities. |
| Starkscan RPC provider beta | JSON-RPC route shape at https://api.starkscan.co/v1/{chain}/rpc with X-Starkscan-Api-Key; use https://starkscan.co/rpc/v0_10/{chain}/{token} for SDKs/tools that require a single nodeUrl. Replace the hosted app/API host with your deployment's host for preview or self-hosted installs. Hosted production is open to Starkscan API-key holders for RPC reads and batch requests; preview/self-hosted deployments may require batch or utility scope unless configured open. Signed transaction submission requires a write-scoped key. |
| Protocol routes | Protocol-domain reads that are hidden until Starkscan exposes them explicitly. |
| Internal-only | App or operations traffic—not part of your integration contract unless Starkscan documents it for you. |
Route certification
Every public OpenAPI operation carries x-starkscan-certification. Agents should read it before deciding whether a route is safe for unattended production use.
| State | Meaning |
|---|---|
certified | Production-safe route: stable schema, monitored path, and current correctness evidence against Starknet RPC or the declared source of truth. |
beta | Usable by named clients, but still has incomplete parity breadth, partner scoping, or known operational limits. |
experimental | Internal or partner preview. Do not build hard dependencies without explicit agreement. |
unsupported | Not a client contract. |
For launch, the certified set is intentionally narrow: status, block-by-id, timestamp-to-block, tx-by-hash, token total supply, and token balance-of. Indexed analytics and protocol-specific routes graduate only after their reconciliation gates are in place.
block-at-timestamp is certified for accounting workflows that resolve an
instant such as 2025-12-31T23:59:59Z with closest=before, then pass the
returned block number to certified balance-of. It does not certify
portfolio-wide historical holdings or ticker-symbol inference.
The public state stays intentionally small. Internal evidence dimensions such
as x-starkscan-oracle, x-starkscan-evidence-level,
x-starkscan-certification-scope, and x-starkscan-slo-class describe how the
route was proved. See Route Certification.
Responses you should handle
| Signal | Action |
|---|---|
X-Request-Id | Include it when you report a bug or ask for support. |
X-Starkscan-Route-Class | Route budget class agents can use for class-specific backoff (light, heavy, or batch). |
Retry-After | Honor it on retries instead of hammering the API. |
exact / truncated (holdings) | For portfolio-style decisions, treat holdings as complete only when exact=true, truncated=false, and completeness.reasonCode="complete". |
Surfaces
REST, the TypeScript SDK, and the CLI share the public REST contract. MCP exposes the same objects through a separate tool surface. Starkscan RPC is an authenticated HTTP beta for clients that need Starknet RPC method names instead of REST routes. It requires a Starkscan API key and is not a full unrestricted provider replacement.
| Surface | Role |
|---|---|
| REST | Direct HTTP; see API reference. |
| Starkscan RPC | Starknet JSON-RPC provider beta; see Starkscan RPC. |
| TypeScript SDK | Typed client; see SDK. |
| CLI | Shell; see Agent CLI. |
| MCP | Tools for coding agents over the MCP / JSON-RPC surface; see MCP quickstart. |