Classify addresses in bulk

Use this guide when you already have a bounded list of wallets or contracts and need one request to answer:

• is this address deployed?
• is it likely an account or contract?
• what class hash or deployment evidence is indexed?
• does Starkscan have a readable label or protocol attribution?
• has the address ever received indexed token transfers?
• when was the latest indexed activity?

These routes are designed for wallet, paymaster, migration, and account-intelligence backends. They use indexed read models only. They do not call Starknet RPC, run deployment repair, scan raw activity, run sanctions/risk screening, or perform heuristic mixer-proximity analysis on the request path.

Pick the light or rich route

Both routes are advanced-utility routes and require a utility or batch-scope API key. Standard read keys can return 403 on these batch helpers.

Contract

• Body key is addresses.
• Maximum batch size is 128 addresses.
• Results preserve the request order after validation.
• Duplicate addresses are rejected by the SDK helpers before a request is sent.
• The API validates Starknet felt-style 0x addresses and returns 400 for malformed input.
• 429 means the route-class budget is exhausted; honor Retry-After.
• 503 means a bounded serving query timed out; honor Retry-After when present. These batch timeout responses currently use Retry-After: 2.

HTTP

export STARKSCAN_API_KEY="YOUR_STARKSCAN_API_KEY"
export STARKSCAN_CHAIN="${STARKSCAN_CHAIN:-SN_MAIN}"
STARKSCAN_BASE_URL="${STARKSCAN_BASE_URL:-https://api.starkscan.co}"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $STARKSCAN_API_KEY" \
  -d '{"addresses":["0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a","0x259fec57cd26d27385cd8948d3693bbf26bed68ad54d7bdd1fdb901774ff0e8"]}' \
  "$STARKSCAN_BASE_URL/v1/$STARKSCAN_CHAIN/address/intelligence"

TypeScript SDK

import { createStarkscanClient } from '@starkscan/sdk';

const starkscan = createStarkscanClient({
  apiKey: process.env.STARKSCAN_API_KEY,
  chainId: process.env.STARKSCAN_CHAIN || 'SN_MAIN',
});

const addresses = [
  '0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a',
  '0x259fec57cd26d27385cd8948d3693bbf26bed68ad54d7bdd1fdb901774ff0e8',
];

const intelligence = await starkscan.addressIntelligence(addresses);

for (const item of intelligence.items) {
  console.log({
    address: item.address,
    label: item.label,
    labelSource: item.labelSource,
    typeLabel: item.typeLabel,
    typeLabelSource: item.typeLabelSource,
    protocol: item.protocol?.name ?? null,
    isDeployed: item.isDeployed,
    classHash: item.classHash,
    classLabel: item.classLabel,
    classLabelSource: item.classLabelSource,
    hasReceivedFunds: item.hasReceivedFunds,
    latestActivityBlock: item.latestActivityBlock,
    source: item.source,
  });
}

CLI

starkscan --output-format json address-intelligence \
  0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a \
  0x259fec57cd26d27385cd8948d3693bbf26bed68ad54d7bdd1fdb901774ff0e8

For larger local lists, put one address per line. Blank lines and lines starting with # are ignored before validation:

starkscan --output-format json address-intelligence --file addresses.txt

Use address-summaries when you want the lighter aggregate view:

starkscan --output-format json address-summaries \
  0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a \
  0x259fec57cd26d27385cd8948d3693bbf26bed68ad54d7bdd1fdb901774ff0e8

Field semantics

Data honesty rules

• Use null as unknown. Do not convert it to false.
• Do not treat missing labels as proof that an address is not a protocol or contract.
• Do not treat account type/template labels as equivalent to curated entity names; class-hash labels, when present, must be stored separately from counterparty label provenance.
• Do not treat hasReceivedFunds=false as proof of zero current balance; use token holdings or exact token balance-of when balances matter.
• Do not treat classLabel as a unique address name. It describes the reviewed class family behind the indexed classHash, while label remains the curated/token address label.
• Do not treat classHash as a current-state proof after upgrades. It is indexed read-model metadata, not a request-path RPC lookup.
• Do not treat this route as compliance screening. It returns factual indexed classification and attribution only, not risk scores, sanctions screening, or mixer-proximity heuristics.
• Keep the original request list so you can join by position as well as by returned address.

Production pattern

1. Validate and deduplicate the address list in your backend.
2. Keep each batch at or below 128 addresses.
3. Call address/intelligence for the rich first pass.
4. Store source, activityCountExact, and nullable fields so downstream jobs can distinguish unknown from false.
5. For detailed wallet views, follow up with address/{address}/activity, address/{address}/transactions, or token holdings on only the addresses a user opens.

For a complete multi-wallet starter across REST, SDK, and CLI, use Monitor 10 wallets.