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

Related non-default route

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 any indexed ERC-20 contract and need a complete holder census
• results come from retained immutable finalized generations, not request-time transfer replay or RPC enumeration
• preserve generationId, asOfBlock, asOfBlockHash, rowDigest, and expiresAt while paging to nextCursor=null
• restart from page one after an invalid_request cursor error; expired or cross-scope cursors never fall back to the latest generation
• 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}/assets/discovery, block-pinned POST /v1/{chain}/query/wallet-state, 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, what generic account/contract type is known, 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. typeLabel is a generic account/contract type derived from indexed account-kind evidence, not a curated name tag. classLabel is a nullable reviewed class-family label derived from the indexed classHash, also not a unique address name tag. 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 retained-history workflows, topic0-only searches may keep paging with nextCursor. Later-position filters require topic0 and explicit numeric bounds. Ordinary read keys are limited to 10,000 inclusive blocks; Wallet workspaces may exceed that limit only for ready selector-position coverage advertised by eventSearch.fullRange.selectorCoverage in /v1/meta/capabilities. Coverage is dynamic, so do not hard-code the currently certified selector list. A malformed request returns 400 invalid_request and must be corrected. An undeclared selector returns 422 full_range_selector_not_supported and is not retryable until capabilities change. Declared coverage that is not ready for the requested range returns 503 event_key_index_coverage_unavailable; honor Retry-After when present. Starkscan does not support unfiltered whole-chain event exports or arbitrary event-data substring scans on this route.

Wallet builders and wallet infrastructure providers that need a Wallet-plan key or selector-position certification can contact Omar with their expected routes, request rate, chain, selectors, and key positions.

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 filters; positional topic0..topic15 filters on both event routes; OR within one position, AND across populated positions, and omitted-position wildcards; stable cursor pagination. selector aliases topic0. The contract route accepts sequential key/keys compatibility values, while the global route requires explicit positions. Any topic1..topic15 filter requires topic0 plus explicit numeric from_block and to_block; address does not replace topic0. Ordinary keys are bounded to 10,000 blocks. Wallet workspaces may request certified larger ranges after verifying the selector-position coverage and range in /v1/meta/capabilities. Only topic0-only searches may omit numeric bounds.

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}/contract/{address}/write-payload
• GET /v1/{chain}/contract/{address}/snapshot

The former portfolio-live helper was removed. Use the published bounded query/wallet-state contract; do not probe the retired path.

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.