External helper routes that are published, supported, and narrower than the main public lane.

Advanced utilities

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.

For wallet, paymaster, migration, or account-intelligence backends, start with the dedicated Classify addresses in bulk guide. It explains the difference between the light summaries route and the richer intelligence route, including null and inexact-field semantics.

Routes

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 controlled batch workflows	`utility`
`POST /v1/{chain}/address/intelligence`	you already have addresses and need deployment, attribution, and inbound-funds flags for migration/compliance workflows	`utility`

This lane is about supported routes that sit outside the default read-key starting set.

GET /v1/{chain}/token/{token}/holders is in that same partner tier — it differs only in being a GET holder census, not in access tier.

use it when you start from a token contract and need a paginated holder census
results come from indexed balance snapshots, not transfer-history replay
treat 403 there as access-tier evidence, not as a malformed request

Example:

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/token/<token>/holders?limit=100"

Quickstart

Shared rules:

If 401, fix the missing or invalid API key before retrying.
If 403, fix the key tier before you blame the payload.
If 429, honor Retry-After (and X-Starkscan-Route-Class) and do not hammer batch helpers in a tight loop.
Prefer one tx or one address routes when they already do the job.
Do not treat these as a substitute for careful paging on high-volume lists.

Copy these example values once, then run any snippet below:

: "${STARKSCAN_API_KEY:?set STARKSCAN_API_KEY first}"
STARKSCAN_BASE_URL="${STARKSCAN_BASE_URL:-https://api.starkscan.co}"
export STARKSCAN_CHAIN="${STARKSCAN_CHAIN:-SN_MAIN}"
export STARKSCAN_EXAMPLE_ADDRESS_A="0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a"
export STARKSCAN_EXAMPLE_ADDRESS_B="0x259fec57cd26d27385cd8948d3693bbf26bed68ad54d7bdd1fdb901774ff0e8"
export STARKSCAN_EXAMPLE_TOKEN="0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
export STARKSCAN_EXAMPLE_TX_A="0x6bc60ea18f4ed87c3dfad515abaef7fc02242eb26793d7dd9e6a0aa5d890fb5"
export STARKSCAN_EXAMPLE_TX_B="0x1cc5558d517495b4605efd6e6293f8d71e4c3659944763db37ff4321a7bce26"
export STARKSCAN_APPROVAL_TOPIC0="0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
export STARKSCAN_APPROVAL_OWNER="0x5983efa05a23ecc4eb29d8717f86b34412964ea152d6a499ea447fcf5f5ee39"
export STARKSCAN_APPROVAL_SPENDER="0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8"
export STARKSCAN_EVENT_FROM_BLOCK="10630000"
export STARKSCAN_EVENT_TO_BLOCK="10630325"

Batch transaction previews

Body key must be hashes, not txHashes or transactions.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  -d "{\"hashes\":[\"$STARKSCAN_EXAMPLE_TX_A\",\"$STARKSCAN_EXAMPLE_TX_B\"]}" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/tx/previews"

Batch address summaries

Body key must be addresses, not wallets, owners, or contracts.

address/summaries is optimized for bounded navigation and controlled batch workflows. It returns request-ordered indexed facts and does not run raw activity scans, deployment repair, or RPC calls on the request path. When the route reports activityCountExact=false, treat the count as intentionally inexact batch metadata, not as proof that the address has no more activity.

For field semantics and a production wallet-backend pattern, see Classify addresses in bulk.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  -d "{\"addresses\":[\"$STARKSCAN_EXAMPLE_ADDRESS_A\",\"$STARKSCAN_EXAMPLE_ADDRESS_B\"]}" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_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.

Batch address intelligence

Body key must be addresses, not wallets, owners, or contracts.

Use this for bounded utility checks such as: "for this list of addresses, tell me whether each address is deployed, what readable label Starkscan has indexed, and whether indexed token transfers show it has ever received funds." The route is indexed-only and does not call RPC, raw activity scans, or deployment repair on the request path.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  -d "{\"addresses\":[\"$STARKSCAN_EXAMPLE_ADDRESS_A\",\"$STARKSCAN_EXAMPLE_ADDRESS_B\"]}" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/address/intelligence"

hasReceivedFunds=true means the address appears as to_addr in indexed token-transfer rows. label and protocol are nullable indexed attribution hints. isDeployed=true means Starkscan has indexed class/deployment evidence for the address. Use the single-address attribution or contract metadata routes when you need richer context for one address.

The route returns items in request order and applies the same validation and capacity limits as address/summaries.

Event search

Event search is a read-tier route, not an advanced-utility batch helper. Use it when a partner workflow needs indexed event rows such as Approval events by selector and bounded block range.

For full indexed-history workflows, use a selective server-side filter and keep paging with nextCursor; do not loop over narrow RPC block windows from your backend. A good production query includes at least a contract address, a selector/topic, or both. Starkscan does not support unfiltered whole-chain event exports or arbitrary event-data substring scans on this route.

Global event search:

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/events?topic0=$STARKSCAN_APPROVAL_TOPIC0&address=$STARKSCAN_EXAMPLE_TOKEN&from_block=$STARKSCAN_EVENT_FROM_BLOCK&to_block=$STARKSCAN_EVENT_TO_BLOCK&limit=100"

Contract-scoped event search:

curl \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/$STARKSCAN_CHAIN/contract/$STARKSCAN_EXAMPLE_TOKEN/events?topic0=$STARKSCAN_APPROVAL_TOPIC0&topic1=$STARKSCAN_APPROVAL_OWNER&topic2=$STARKSCAN_APPROVAL_SPENDER&from_block=$STARKSCAN_EVENT_FROM_BLOCK&to_block=$STARKSCAN_EVENT_TO_BLOCK&limit=100"

Supported boundaries: repeated address and topic0 filters on /events; exact topic0, topic1, topic2, and topic3 filters on /contract/{address}/events; optional from_block/to_block; cursor pagination. Use block bounds when you want a fixed historical window. Omit them only for selective full-history scans that page with nextCursor.

Rules

The request body key is hashes for tx/previews.
The request body key is addresses for address/summaries.
The request body key is addresses for address/intelligence.
401 Unauthorized means the key is missing or invalid; fix auth before retrying.
address/summaries is for controlled batch hydration, not canonical freshness proof.
address/intelligence is for bounded utility classification, not a replacement for event search.
403 Forbidden usually means the key lacks utility or batch-scope access.
429 Too Many Requests means back off and honor Retry-After.
503 Service Unavailable means a bounded serving query timed out; honor Retry-After when present. Address batch timeout responses currently use Retry-After: 2; retry later or send a smaller batch.
Use this lane for published batch helpers, not canonical single-item proofs.
If a simpler official route fits the job, use the simpler route.

Not in this lane

These helper routes are intentionally not part of the published advanced-utilities lane today:

POST /v1/{chain}/address/{address}/portfolio-live
POST /v1/{chain}/contract/{address}/write-payload
GET /v1/{chain}/contract/{address}/snapshot

Why:

they are easier to misuse without context
some are wallet-helper or operational routes rather than core explorer reads
contract/{address}/snapshot is a best-effort composed helper, not canonical chain truth

Agent rule

If a route is not in /api-reference or this page, do not assume it is part of the external contract.

Advanced Utilities