API discovery

Start integrations with discovery instead of copying a route list from prose. Starkscan publishes three complementary machine-readable contracts:

The REST capabilities document is caller-specific and always uses Cache-Control: no-store. It never includes an API-key value or identifier. Use caller.scopes and caller.rateLimit for the current REST key, use rpc.discover for the caller-filtered RPC method set, and treat a 403 or 429 plus its response headers as authoritative for that request.

Read the capabilities contract

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/meta/capabilities"

Validate the response against starkscan-meta-capabilities.schema.json. The contract is additive: reject an unknown schemaVersion only when your client cannot safely ignore new fields.

The important blocks are:

• firstCalls: a bounded bootstrap sequence.
• documentation: the public OpenAPI URL and JSON-Pointer lookup rule.
• routeFamilies[].operations[]: runtime-filtered method, external path, OpenAPI path, response rateLimitClass, summary, and openapiOperationRef.
• rateLimit: the X-Starkscan-Route-Class, X-RateLimit-*, and Retry-After contract. A batch route is a workload class, not a discount.
• sessionControl: /v1/me/* is a Better Auth session boundary. API keys are deliberately unsupported there.
• apiKeyLifecycle: revoked or expired keys receive the same generic 401 unauthorized body and WWW-Authenticate: Bearer realm="starkscan", error="invalid_token"; throttling remains 429 with Retry-After.
• caller: the current auth type, sanitized key class, scopes, and rate-limit window without key identity.
• rpcProvider, walletInteraction, and operatingRules: provider shape, write gates, cursor/order rules, list-row omissions, and search behavior.

Discover JSON-RPC methods

Call service discovery on the preferred header-auth server endpoint:

curl "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/api/v1/SN_MAIN/rpc" \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"rpc.discover","params":[]}'

The result is deterministic for the runtime and caller authorization. Discovery never contacts an upstream provider. Do not cache one caller's result for a different key.

Resolve a REST operation

Choose the smallest operation in routeFamilies[].operations[], fetch documentation.openapiUrl, percent-decode the fragment in openapiOperationRef once, and resolve it as a JSON Pointer. That operation is authoritative for parameters, request bodies, response schemas, examples, and the response rate-limit class.

This avoids learning route shapes from 400 responses or assuming that two keys expose the same operations.

Operating rules that commonly break clients

• /v1/me/* accepts a signed-in Better Auth session, not X-Starkscan-Api-Key. Programmatic key capabilities live in caller.
• Transfer lists are newest-first. Treat cursors as opaque and pass them back unchanged.
• Lightweight transfer rows intentionally omit historicalUsd; fetch the documented detail/enrichment surface when historical pricing is required.
• Search is identifier-only: block numbers, exact felt-like identifiers, and indexed address prefixes. Token symbols, names, tickers, labels, and free text are unsupported.
• Empty and oversized batches are rejected before child dispatch. Read rpcProvider.batch.maxItems and rpcProvider.batch.maxResponseBytes instead of probing larger payloads.

Bootstrap from only a host

curl "https://starkscan.co/.well-known/api-catalog"

The catalog links to OpenAPI, this guide, the capabilities schema, the authenticated capabilities endpoint, and status. Continue with the Agent HTTP quickstart, Starkscan RPC, or the complete API reference.