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 all external integrations — ignore any other header names you may see in older snippets.
curl -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
"$STARKSCAN_BASE_URL/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 once, as X-Starkscan-Api-Key. |
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.