API

REST API for exact request shapes, auth, pagination, and retries.

API reference Reference Quickstart TypeScript SDK

In this guide

Hosted external base Start here Public core API (OpenAPI tags)API surface tiers Quickstart Common reads

Loading documentation content…

API

Use the REST API when you need the exact hosted contract.

Fast path: Interactive API reference (full operation list + try-it) · Reference hub · Download OpenAPI YAML

Hosted external base

export MEZCAL_BASE_URL="https://<your-mezcal-host>/api"
export MEZCAL_API_KEY="mzk_test_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"

Hosted route format:

$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/...

Start here

API reference
Concepts — base URL, auth, tiers, cursors
API surface policy — what is public, advanced, or internal-only
Advanced utilities — published batch previews, detail hydration, and address summaries
Monitor 10 wallets — one starter, three surfaces
Protocol routes · Protocol reference

Public core API (OpenAPI tags)

The published mezcal-openapi.yaml groups operations under the tags below. Each group expands in the API reference sidebar to every path and method—use that as the exhaustive catalog; this table is the map, not a second source of truth.

Tag	What it covers
Addresses	Aggregate address view, paginated txs touching an address, token holdings, activity feeds
Analytics	Chain- and protocol-level analytics where exposed in the public contract
Blocks	Block metadata and listings
Contracts	Class, verification, reads, and contract-scoped resources
Search	Explorer search over entities surfaced by the API
Status	Chain status and health-style reads
Tokens	Token metadata, supply, balances, transfers
Transactions	Transaction detail, previews, and related reads
Utilities	Supported helper routes (may require broader key tiers—see Advanced utilities)

Bridge analytics protocol extensions live in a separate OpenAPI artifact: Protocol routes reference and mezcal-openapi-protocol-extensions.yaml. Private protocol validation surfaces are intentionally not published.

API surface tiers

If you need...	Use...
standard explorer reads	`official public API`
a published batch helper such as tx previews, tx details, or address summaries	`advanced utilities`
public bridge-analytics protocol extension reads	`protocol routes`
hidden app routes or private operational helpers	do not use them externally

Lane definitions:

official public API: default external contract in /docs and /api-reference
advanced utilities: external helper routes that need more context or a broader key tier
protocol routes: public bridge-analytics protocol extensions in the separate protocol OpenAPI artifact
internal-only: not part of the external contract

See API surface policy for the allowlist and exclusions.

Quickstart

curl \
  -H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/status"

curl \
  -H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/{address}/activity?limit=50"

curl \
  -H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/{token}/transfers?address={walletA}&address={walletB}&limit=100"

Common reads

Job	Route
chain status	`GET /v1/{chain}/status`
address activity	`GET /v1/{chain}/address/{address}/activity`
wallet holdings	`GET /v1/{chain}/address/{address}/token-holdings`
token transfers	`GET /v1/{chain}/token/{token}/transfers`
contract events	`GET /v1/{chain}/contract/{address}/events`
contract read	`GET /v1/{chain}/contract/{address}/read`
search	`GET /v1/{chain}/search`

Token reads

Use GET /v1/{chain}/token/{token}/balance-of/{address} only when you already know the exact token contract.
Use GET /v1/{chain}/address/{address}/token-holdings for wallet screening, portfolio checks, or skip lists.
Do not assume one contract per symbol on Starknet. USDC can resolve to multiple live contracts or aliases.
For screening decisions, treat token-holdings as complete only when exact=true and truncated=false.
On very hot wallets, separate latest calls to token-holdings and exact balance-of can drift numerically if the chain moved between requests; a missing core-token row on a completed holdings response is the stronger bug signal.

Current confidence notes

For latest wallet state, prefer address/{address}/activity, address/{address}/token-holdings, exact balance-of, and filtered token/transfers.
Do not use GET /v1/{chain}/address/{address} as your freshest latest-activity source for automation right now.
Do not use GET /v1/{chain}/token/{token} aggregate transfer counters as source of truth right now; use GET /v1/{chain}/token/{token}/transfers.
If you need timestamps on wallet history, prefer address/{address}/activity; address/{address}/transactions can omit timestampIso on preview.
Treat GET /v1/{chain}/analytics/kpis as exploratory until it is revalidated with stable non-empty payloads.

Contract logs

Use GET /v1/{chain}/contract/{address}/events when you need the canonical paginated event stream for one contract.
Filter server-side with topic0..topic3, from_block, and to_block before doing client-side decoding or protocol interpretation.
Topic filters are exact single-value felt matches in this route; this first slice does not support OR-arrays or topic-expression combinatorics.
topic0 is the primary event-selector filter. If you send a topic param, it must be a non-empty felt like 0xabc or 0XABC.
Results are ordered newest first by on-chain position: blockNumber, txIndex, logIndex.
Use the returned nextCursor as an exclusive resume point instead of reconstructing windows from block numbers yourself.

curl \
  -H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/contract/{address}/events?topic0=0x...&from_block=7800000&limit=100"

Agent rules

POST /v1/{chain}/tx/previews expects {"hashes":[...]}.
POST /v1/{chain}/tx/previews defaults to compact previews; ask for includeLogCounts=true or includeLogs=true before you treat logCount=0 or logs=[] as evidence of no logs.
POST /v1/{chain}/tx/details also expects {"hashes":[...]} and returns ordered detail payloads for the found hashes, with logsTruncated and tokenTransfersTruncated flags when bounded child data was clipped.
POST /v1/{chain}/address/summaries expects {"addresses":[...]} and preserves request order for addresses it can resolve. Unresolved or not-found addresses may be omitted, so clients must match returned summaries by address value instead of assuming one-to-one positional alignment; treat inexact activity counts as honest batch-route metadata, not proof that the address has no more activity.
GET /v1/{chain}/contract/{address}/entrypoints can return write-capable external selectors too; for read, prefer selectors marked stateMutability=view and provide calldata when inputs are required.
GET /v1/{chain}/contract/{address}/read requires a raw Starknet selector, not a function name; do not treat non-view or calldata-mismatched selectors as route bugs.
GET /v1/{chain}/search?q=... is identifier-first search, not ticker / symbol search; expect canonical padded felt forms in responses.
GET /v1/{chain}/contract/{address}/verification returning 404 means no verification record exists yet.
403 on an advanced utility usually means key-tier mismatch.
If a route is not in the published reference or in Advanced utilities, do not treat it as part of the external contract.

Errors and retries

Status	Meaning	Client action
`401`	missing or invalid credentials	stop and fix auth
`403`	required scope or route-tier mismatch	stop and fix key tier
`503` with `Retry-After`	temporary unavailability	retry with backoff

Always log X-Request-Id for support and debugging.

Use another surface when

use the TypeScript SDK for typed app code
use the CLI for shell workflows and local exports
use MCP only when the client needs tool calls
stay in the explorer when the job is visual inspection