Concepts
Short definitions shared by the Quickstart, REST guide, and Build pages.
Host and path
| Term | Meaning |
|---|
MEZCAL_BASE_URL | On the hosted external lane, your API root including /api, e.g. https://<host>/api. The explorer UI on the same host talks to the same backend. |
/v1/{chain} | Chain segment in the path. SN_MAIN is Starknet mainnet. Full example: …/api/v1/SN_MAIN/status. |
Same-origin /v1/* | Inside the web app, the browser may call /v1/... via proxy. Integrators following these docs usually use /api/v1/... with a key. |
Auth
| Term | Meaning |
|---|
X-Mezcal-Api-Key | Header you send on every API request. No Bearer prefix—just the key value. |
| 401 | Key missing or not accepted. Fix credentials before retrying. |
| 403 | Key valid but route or tier not allowed (common on batch utility routes). |
Lists and data shape
| Term | Meaning |
|---|
| Cursor pagination | List responses use items and often nextCursor. Pass the cursor back to get the next page. Offsets are not the default model. |
limit | Cap on how many rows one response returns. Keep it modest on hosted APIs. |
Route tiers
| Tier | Meaning |
|---|
| Official public API | Default documented contract in Scalar and mezcal-openapi.yaml. Start here. |
| Advanced utilities | Supported batch helpers (e.g. tx previews, tx detail hydration, address summaries). Often need a broader key. See Advanced utilities. |
| Protocol routes | Public bridge-analytics extension reads. Private protocol validation surfaces are not part of this public spec. |
| Internal-only | App or operations traffic—not part of your integration contract unless Mezcal documents it for you. |
Responses you should handle
| Signal | Action |
|---|
X-Request-Id | Include it when you report a bug or ask for support. |
Retry-After | Honor it on retries instead of hammering the API. |
exact / truncated (holdings) | For portfolio-style decisions, treat holdings as complete only when exact=true and truncated=false. |
Surfaces
REST, the TypeScript SDK, and the CLI share the public REST contract. MCP exposes the same objects through a separate tool surface.
