Concepts
Terms you will see across Starkscan docs—URLs, auth, pagination, and API tiers.
Loading documentation content…
Terms you will see across Starkscan docs—URLs, auth, pagination, and API tiers.
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.
| Term | Meaning |
|---|---|
STARKSCAN_BASE_URL | On the hosted external lane, your API root including /api, e.g. https://<host>/api. The explorer UI on the same host talks to the same backend. |
STARKSCAN_RPC_URL | Full Starkscan JSON-RPC provider URL shape for gated readiness testing, e.g. https://<host>/api/v1/SN_MAIN/rpc with header auth, or https://<host>/rpc/v0_10/SN_MAIN/<token> only when a client cannot attach headers. Do not use it as a production provider replacement until Starkscan publishes provider-readiness proof. |
/v1/{chain} | Chain segment in the path. SN_MAIN is Starknet mainnet. Full example: …/api/v1/SN_MAIN/status. |
Same-origin /v1/* | Inside the web app, the browser may call /v1/... via proxy. Integrators following these docs usually use /api/v1/... with a key. |
| 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. |
| 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. |
| 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 pilot | JSON-RPC route shape at /api/v1/{chain}/rpc with X-Starkscan-Api-Key; use /rpc/v0_10/{chain}/{token} only for SDKs/tools that require a single nodeUrl. This is not a migration-ready provider until a dedicated mainnet RPC upstream passes provider-readiness proof. |
| Protocol routes | Protocol-domain reads that are hidden on preview-main until Starkscan exposes them explicitly. |
| Internal-only | App or operations traffic—not part of your integration contract unless Starkscan documents it for you. |
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.
| 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, list, heavy, profile, 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". |
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 a provider pilot for clients that need Starknet RPC method names instead of REST routes, but customer migration waits for provider-readiness proof.
| Surface | Role |
|---|---|
| REST | Direct HTTP; see API reference. |
| Starkscan RPC | Starknet JSON-RPC provider pilot; see Agent HTTP quickstart. |
| 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. |