Quickstart
Get connected to Starkscan quickly with a public host, a bounded API key, and no repo setup.
Loading documentation content…
Get connected to Starkscan quickly with a public host, a bounded API key, and no repo setup.
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.
Open the live product on the same host before you wire clients:
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.
MEZCAL_BASE_URLMEZCAL_API_KEYMEZCAL_CHAIN if you are not using the default SN_MAINIf you are using the hosted external surface, MEZCAL_BASE_URL should already include /api.
New to the vocabulary? See Concepts.
export MEZCAL_BASE_URL="https://<your-mezcal-host>/api"
export MEZCAL_API_KEY="mzk_live_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"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.
If your editor supports .http request files, start with the exact request shape first:
@mezcal = https://<your-mezcal-host>/api
@chain = SN_MAIN
@apiKey = mzk_live_your_key_here
GET {{mezcal}}/v1/{{chain}}/status
X-Starkscan-Api-Key: {{apiKey}}Shell form of the same request:
curl \
-H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/status"If that returns chain status, your Starkscan access is wired correctly.
These are the fastest replacement checks when you are moving from direct RPC reads into Starkscan:
curl \
-H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/<token>/total-supply?block_tag=latest"
curl \
-H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_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: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/<owner>/token-holdings"That avoids two common mistakes:
balance-of across large wallet sets when token-holdings is the better current Starkscan pathThese 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".
If your workflow looks like Carlos’s wallet monitoring setup, do not hand-assemble it from scattered snippets. Use the dedicated Monitor 10 wallets guide instead.
That starter gives you one canonical workflow across:
npm install -g @mezcal/cli@alpha
mezcal statusFor a one-off run without a global install:
npx @mezcal/cli@alpha statusThe npm package includes the native mezcal CLI artifacts, verifies them before caching the binary locally, and does not require repository access.
If you need a pinned CLI release and have access to the release artifacts:
export MEZCAL_INSTALLER_REF="<release-tag>"
curl -fsSL "https://raw.githubusercontent.com/starknet-innovation/mezcal/${MEZCAL_INSTALLER_REF}/rust-exp/scripts/install-mezcal.sh" | bash -s -- --version "${MEZCAL_INSTALLER_REF}"Manual tarball install remains available as a maintainer fallback after downloading the matching archive from the GitHub release page:
tar -xzf mezcal-<platform>.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 mezcal "$HOME/.local/bin/mezcal"npm install @mezcal/sdk@alpha
# or
pnpm add @mezcal/sdk@alpha
bun add @mezcal/sdk@alphaKeep going with the API guide when you need exact HTTP behavior, auth headers, retries, and request/response debugging.
Use the TypeScript SDK when you want typed responses and route construction handled for you.
Use the Agent CLI when you want repeatable terminal commands, local-first transfer exports, or a shell-friendly operator surface.
Use MCP quickstart when the consumer is Codex, Claude Code, Cursor, VS Code, or another MCP client.
Stay in the browser first when the job is visual verification: