Quickstart

Use this guide when you need the shortest safe path from “I have a host and a key” to “I made a successful Starkscan request.”

Default recommendation: start with direct HTTP first. A requests.http file or curl keeps the auth header, route shape, and wire output visible before you add SDK, CLI, or MCP layers.

Use this guide for

• external API onboarding
• first-request verification
• choosing the right Starkscan surface before deeper integration work
• proving the current deployment is reachable before you touch SDK, CLI, or MCP

Start in the app first

Open the live product on the same host before you wire clients:

• Dashboard
• Transactions
• Contracts
• Watchlist

Use the app first when you want to confirm the deployment is healthy and see the same explorer surface that the API, SDK, CLI, and MCP all sit on top of.

What you need

• STARKSCAN_API_KEY
• optionally STARKSCAN_CHAIN if you are not using the default SN_MAIN
• optionally STARKSCAN_BASE_URL only when targeting preview or a self-hosted Starkscan host

Hosted production defaults to https://api.starkscan.co in the CLI, SDK, and MCP launcher. Create or rotate a key from the hosted API keys page before you paste the examples into an agent, CI job, SDK app, or shell script.

New to the vocabulary? See Concepts.

1. Export the environment

export STARKSCAN_API_KEY="YOUR_STARKSCAN_API_KEY"
export STARKSCAN_CHAIN="SN_MAIN"
# Optional: only set this for preview or self-hosted hosts.
# export STARKSCAN_BASE_URL="https://preview.example.com/api"

All public docs below assume you call the normal /v1/* routes relative to that base.

If you are onboarding a coding agent that will call Starkscan over HTTP directly, start with Agent HTTP quickstart instead of reconstructing a reduced contract from chat snippets.

2. Make the first successful request

If your editor supports .http request files, start with the exact request shape first:

@starkscan = https://api.starkscan.co
@chain = SN_MAIN
@apiKey = YOUR_STARKSCAN_API_KEY

GET {{starkscan}}/v1/{{chain}}/status
X-Starkscan-Api-Key: {{apiKey}}

Shell form of the same request:

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

If that returns chain status, your Starkscan access is wired correctly.

3. Validate the first high-value reads

These are the fastest replacement checks when you are moving from direct RPC reads into Starkscan:

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/token/<token>/total-supply?block_tag=latest"

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/token/<token>/balance-of/<owner>?block_tag=latest"

Use balance-of only when you already know the exact token contract you want to check. If the workflow is wallet screening or "skip wallets that already hold USDC," use:

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/address/<owner>/token-holdings"

That avoids two common mistakes:

• assuming one symbol such as USDC maps to only one Starknet contract
• looping exact-token balance-of across large wallet sets when token-holdings is the better current Starkscan path

These same workflows also exist in the CLI, the TypeScript SDK, and MCP.

If you use token-holdings to decide whether to skip or include a wallet, check the holdings completeness flags first. Treat the result as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".

4. Run the 10-wallet monitoring starter

If your workflow is fixed-wallet monitoring, do not hand-assemble it from scattered snippets. Use the dedicated Monitor 10 wallets guide instead.

That starter gives you one canonical workflow across:

• HTTP for zero-install monitoring and raw wire inspection
• the TypeScript SDK for app code
• the CLI for shell-based polling and local exports

5. Install the release clients

CLI

npm install -g @starkscan/cli
starkscan init
starkscan status

For a one-off run without a global install:

npx -y @starkscan/cli init --agent --output-format json

The npm package includes the native Starkscan CLI artifacts, verifies them before caching the binary locally, and does not require repository access.

Pinned native artifacts remain a maintainer fallback; public users should start with npm.

SDK

npm install @starkscan/[email protected]
# or
pnpm add @starkscan/[email protected]
bun add @starkscan/[email protected]

Default installs use latest. Pin exact 0.1.2 for unattended agents and services.

6. Choose the next surface deliberately

Stay on HTTP when you want zero-install integration

Keep going with the API guide when you need exact HTTP behavior, auth headers, retries, and request/response debugging.

Move to the SDK when you are writing app code

Use the TypeScript SDK when you want typed responses and route construction handled for you.

Move to the CLI when you need shell workflows or exports

Use the Agent CLI when you want repeatable terminal commands, local-first transfer exports, or a shell-friendly operator surface.

Move to MCP when an agent needs tool-calling access

Use MCP quickstart when the consumer is Codex, Claude Code, Cursor, VS Code, or another MCP client.

7. Keep going with the right docs

• Continue with the API guide when you need exact HTTP behavior.
• Continue with Agent HTTP quickstart when a coding agent needs a bounded HTTP route set.
• Continue with the SDK when you are writing app code.
• Continue with the CLI when you want shell workflows or local exports.
• Continue with MCP when an agent needs tool calls instead of direct HTTP.

When to stay in the explorer instead

Stay in the browser first when the job is visual verification:

• use Transactions to inspect activity and detail pages
• use Contracts to inspect deployment metadata and holdings
• use Watchlist to revisit saved high-signal entities
• use Dashboard when you need quick chain-health context