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}/address/summaries | you already have addresses and want ordered aggregate summaries for navigation or partner batch workflows | utility |
This lane is about supported routes that sit outside the default read-key starting set.
GET /v1/{chain}/token/{token}/holders is also in that category, but it is partner tier rather than utility.
403 there as access-tier evidence, not as a malformed requestExample:
curl \
-H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/<token>/holders?limit=100"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-Starkscan-Api-Key: $MEZCAL_API_KEY" \
-d '{"hashes":["0xabc","0xdef"]}' \
"$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/tx/previews"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-Starkscan-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.addresses for address/summaries.401 Unauthorized means the key is missing or invalid; fix auth before retrying.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 or this page, do not assume it is part of the external contract.