Build

Choose the right Starkscan integration surface for code and automation.

API reference Reference Quickstart TypeScript SDK

In this guide

Surface map Start here Public labels Shared env Agent-readable files Client rules

Loading documentation content…

Build

Choose the Starkscan surface by job.

Public clients and agents should treat this docs host as the source of truth for install names, launch state, and package trust. The engineering repository is private; do not depend on GitHub links for public onboarding.

Surface map

If you need...	Use...
exact HTTP contract, auth, retries, pagination	REST API
typed application code	TypeScript SDK
shell workflows or local exports	Agent CLI
tool-calling access for an agent	MCP

Start here

Public labels

Surface	Public label	Use it when
REST core API	`certified`	You need the exact wire contract and the production-safe certified route set.
TypeScript SDK	`alpha`	You want typed application code over the same hosted REST contract.
Agent CLI	`alpha`	You want shell workflows, JSON output, or local exports.
Hosted MCP	`beta` hosted / `alpha` launcher	Your client already speaks MCP and should use the hosted `/api/mcp` transport.

Shared env

export STARKSCAN_BASE_URL="https://<your-starkscan-host>/api"
export STARKSCAN_API_KEY="mzk_live_your_key_here"
export STARKSCAN_CHAIN="SN_MAIN"

All build surfaces use the same hosted contract underneath.

Agent-readable files

public-client-surface-matrix.json tells agents the machine launch state, package channel, and evidence for REST, SDK, CLI, and MCP surfaces.
starkscan-openapi.yaml is the public HTTP contract.
/llms.txt and /llms-full.txt expose the docs map for LLM crawlers.

Client rules

always send X-Starkscan-Api-Key
treat 401 as missing or invalid credentials
treat 403 as a real scope or route-tier mismatch
treat 429 as a route-class budget hit and honor Retry-After
honor Retry-After on 503
log X-Request-Id
do not assume hidden /v1/* app routes are external

Pagination

High-cardinality routes are cursor-based.

Expect:

bounded limit parameters
items arrays
nextCursor when another page exists
repeated query parameters where documented, for example multiple address= filters on token transfers

Representative routes:

GET /v1/{chain}/address/{address}/activity?limit=50
GET /v1/{chain}/token/{token}/transfers?address=0xA&address=0xB&limit=100

Concurrency

Treat the hosted /api lane as a bounded external service:

keep concurrency bounded
page deliberately
honor Retry-After
prefer incremental monitoring loops over chain-scale refetches

For multi-wallet monitoring, use Monitor 10 wallets.