Quickstart
Get connected to Mezcal quickly with a public host, a bounded API key, and no repo setup.
Loading documentation content…
Get connected to Mezcal 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 Mezcal request.”
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_test_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"All public docs below assume you call the normal /v1/* routes relative to that base.
curl \
-H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/status"If that returns chain status, your Mezcal access is wired correctly.
These are the fastest replacement checks when you are moving from direct RPC reads into Mezcal:
curl \
-H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/<token>/total-supply?block_tag=latest"
curl \
-H "X-Mezcal-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-Mezcal-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 Mezcal 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 and truncated=false.
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:
export MEZCAL_INSTALLER_REF="<release-tag-or-commit-sha>"
curl -fsSL "https://raw.githubusercontent.com/starknet-innovation/mezcal/${MEZCAL_INSTALLER_REF}/rust-exp/scripts/install-mezcal.sh" | bash
mezcal statusIf you need a pinned CLI release:
curl -fsSL "https://raw.githubusercontent.com/starknet-innovation/mezcal/${MEZCAL_INSTALLER_REF}/rust-exp/scripts/install-mezcal.sh" | bash -s -- --version <tag>Manual tarball install remains available as a 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 REST API 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: