Advanced Utilities
External helper routes that are published, supported, and narrower than the main public lane.
Loading documentation content…
External helper routes that are published, supported, and narrower than the main public lane.
Use this lane when the official public API is correct but too chatty for a controlled batch workflow.
These routes are external and supported. They are not the default starting point for new integrations.
| Route | Use when | Key tier |
|---|---|---|
POST /v1/{chain}/tx/previews | you already have tx hashes and want ordered lightweight previews | utility |
POST /v1/{chain}/tx/details | you already have tx hashes and want ordered detail hydration with bounded child payloads | utility |
POST /v1/{chain}/address/summaries | you already have addresses and want ordered aggregate summaries for navigation or partner batch workflows | utility |
Shared rules:
Retry-After and do not hammer batch helpers in a tight loop.Body key must be hashes, not txHashes or transactions.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
-d '{"hashes":["0xabc","0xdef"]}' \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/tx/previews"Body key must be hashes, not txHashes or transactions.
Defaults are compact on purpose:
hashes in the request, tx/details returns logs=[] and logCount=0.includeLogs=true, includeLogCounts defaults to true and the response includes exact counts.includeLogCounts=true and leave includeLogs unset or false.curl -X POST \
-H "Content-Type: application/json" \
-H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
-d '{"hashes":["0xabc","0xdef"],"logLimitPerTx":32}' \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/tx/details"Body key must be addresses, not wallets, owners, or contracts.
address/summaries is optimized for bounded navigation and partner batch workflows. It returns items in request order for the addresses it can resolve. When the route reports activityCountExact=false, treat the count as intentionally inexact batch metadata, not as proof that the address has no more activity.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Mezcal-Api-Key: $MEZCAL_API_KEY" \
-d '{"addresses":["0xabc","0xdef"]}' \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/summaries"Use GET /v1/{chain}/address/{address}/activity, GET /v1/{chain}/address/{address}/token-holdings, exact GET /v1/{chain}/token/{token}/balance-of/{address}, or filtered GET /v1/{chain}/token/{token}/transfers when freshest per-address evidence matters.
hashes for tx/previews.hashes for tx/details.addresses for address/summaries.401 Unauthorized means the key is missing or invalid; fix auth before retrying.tx/details rejects duplicate hashes, including padded and unpadded variants of the same tx hash.tx/details returns the detail shape in request order for the found hashes, but this batch route can set logsTruncated or tokenTransfersTruncated per item.tx/details is intentionally capped more tightly than tx/previews; keep batches small and split large hydration jobs client-side.address/summaries is for controlled batch hydration, not canonical freshness proof.403 Forbidden usually means the key lacks utility access.503 Service Unavailable means back off and honor Retry-After when it is present.These helper routes are intentionally not part of the published advanced-utilities lane today:
POST /v1/{chain}/address/{address}/portfolio-livePOST /v1/{chain}/contract/{address}/write-payloadGET /v1/{chain}/contract/{address}/snapshotWhy:
contract/{address}/snapshot is a best-effort composed helper, not canonical chain truthIf a route is not in /api-reference, Protocol routes, or this page, do not assume it is part of the external contract.