API Surface Policy
Which Mezcal routes are official public API, advanced utilities, protocol routes, or internal-only.
Loading documentation content…
Which Mezcal routes are official public API, advanced utilities, protocol routes, or internal-only.
Mezcal publishes three external lanes and keeps operational helpers out of the default contract.
| Tier | Contract | Where to verify |
|---|---|---|
| Official public API | Default stable explorer reads for integrators, SDKs, CLI workflows, and direct REST clients. | API reference and mezcal-openapi.yaml |
| Advanced utilities | Supported helper routes for controlled batch workflows. They can require broader utility-access keys and tighter client-side batching discipline. | Advanced utilities and the Utilities tag in mezcal-openapi.yaml |
| Protocol routes | Public bridge-analytics extension reads. Private protocol validation surfaces are not published. | Protocol routes and mezcal-openapi-protocol-extensions.yaml |
| Internal-only | App bootstrap, operations, probes, MCP transport, or private mutation helpers. | Not published for external integration. |
These helpers are published and supported, but they are not the default starting point for new integrations:
| Route | Use when |
|---|---|
POST /v1/{chain}/tx/previews | you already have tx hashes and want ordered lightweight previews |
POST /v1/{chain}/tx/details | you already have tx hashes and want ordered detail hydration with bounded child payloads |
POST /v1/{chain}/address/summaries | you already have addresses and want ordered aggregate summaries for a controlled batch workflow |
address/summaries is batch-oriented. If a response marks activity counts as inexact, treat that as honest metadata for the batch route. Use GET /v1/{chain}/address/{address}/activity, GET /v1/{chain}/address/{address}/token-holdings, or exact token reads when freshest per-address evidence matters.
These routes are intentionally hidden from the default public OpenAPI contract:
| Route | Status |
|---|---|
POST /v1/{chain}/address/{address}/portfolio-live | unpublished helper; use token holdings and exact token reads externally |
POST /v1/{chain}/contract/{address}/write-payload | unpublished wallet-helper payload builder |
GET /v1/{chain}/contract/{address}/snapshot | internal app/bootstrap aggregate, not canonical chain truth |
GET /v1/{chain}/feed and GET /v1/{chain}/feed/stream | app feed / streaming surface, not part of the default REST contract |
GET /v1/{chain}/analytics/overview-metrics | internal dashboard aggregate, not part of the default REST contract |
POST /v1/{chain}/analytics/kpis/recompute | operational mutation |
GET /v1/{chain}/address/{address}/events | internal event explorer helper; use the documented address activity surfaces externally |
| Private protocol validation routes | not published for external integration |
/healthz, /readyz, /livez, /metrics, /mcp | probes or transport endpoints, not REST integration routes |
/.well-known/oauth-protected-resource | OAuth discovery metadata, not an explorer REST integration route |
For public-core docs, the generated OpenAPI marks advanced utilities with:
x-mezcal-surface-tier: advanced-utilityx-mezcal-key-tier: utilityIf a route is not in /api-reference, Advanced utilities, or Protocol routes, do not assume it is part of the external contract.