Authentication
Send X-Starkscan-Api-Key on every request, and how to read 401, 403, and 429 responses.
Authentication
One header authenticates every Starkscan API request.
The header
X-Starkscan-Api-Key: <your key>Send the raw key value with no Bearer prefix. Get a key from Get your first API key. Use X-Starkscan-Api-Key for server and other external integrations. Browser-direct REST clients may use X-Api-Key as the browser-compatible alias; ignore legacy header names from older snippets.
curl -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
"${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/status"Keep your key secret
Store the key in an environment variable or secrets manager. Never commit it or paste it into chat, tickets, screenshots, or PR comments. Rotate immediately if the full value appears in logs.
Errors
| Status | Meaning | What to do |
|---|---|---|
401 | Key missing or not accepted | Fix credentials before retrying. |
403 | Key valid, but the route or tier is not allowed (common on batch / advanced-utility routes) | Use a route in your tier; see Advanced utilities. |
429 | Rate limit reached for the current route class | Honor Retry-After; back off per X-Starkscan-Route-Class. See Rate limits. |
400 conflicting_api_key_headers | The key was sent under more than one header | Send it exactly once, using X-Starkscan-Api-Key (recommended) or X-Api-Key for browser-direct REST clients. |
400 malformed_api_key_header | The header value is not a valid key | Check for stray quotes or whitespace. |
Errors use a JSON envelope:
{
"code": "rate_limited",
"message": "Rate limit exceeded; retry shortly",
"docSlug": "api/rate-limits",
"requestId": "mzk-..."
}Log X-Request-Id when you report an issue so support can correlate it.
Tiers and access
Most documented reads work with a standard key. Some batch and advanced-utility routes need a broader tier and return 403 otherwise — see Advanced utilities. For per-route budgets and the route classes you should back off on, see Rate limits.
Read your key's usage
curl -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
"${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/api-key/usage"On the explorer host, use /api/v1/api-key/usage. The endpoint requires a
workspace API key with read or prove scope and returns only that key's last 24 hours:
totalRequests, totalFailures, perKey, recentRequests, and recentFailures,
with window timestamps and truncation flags. Recording is asynchronous and best
effort; these are recorded HTTP requests, not billing totals or individual RPC
batch calls. Rate-limit state is the last observation, not a live quota balance.
Normal read rate limits apply, and the usage request itself is recorded afterward.
Responses are not cacheable. Sessions, OAuth, internal, and environment-configured
keys are not supported for this endpoint.
The SDK exposes the same authenticated snapshot as await client.apiKeyUsage().
From the CLI, run starkscan api-key-usage --output-format json; the configured API key
is used and the selected chain does not filter the account-level usage window.
Use this REST endpoint or the SDK/CLI with a workspace key when monitoring your
own integration.
The same response includes proofUsage for this key's mainnet proofs today
(UTC). Use proofUsage.succeededToday for successful completions, including
jobs submitted before midnight. failedToday, unavailableToday, and
unknownDeliveryToday are separate terminal outcomes; queued and running
show current unfinished work. These counters come from the durable job ledger.
admittedToday is the daily quota usage: every admitted job consumes one unit,
including failed jobs. Polling and idempotent replays do not consume another
unit. dailyLimit reflects the per-key override or relay default, and
remainingToday is the nonnegative difference. Both are null when relay
configuration is unavailable on the API instance. Remaining budget does not
guarantee admission: proving scope, relay availability, and concurrency limits
still apply. windowEnd is the next UTC midnight; observedAt is the snapshot
time. This daily window is separate from the HTTP telemetry's rolling 24 hours.