Route examples

Exact examples for Starkscan routes that agents most often misread: block reads, search, trace, contract reads, previews, and holdings.

API reference Reference Quickstart TypeScript SDK

In this guide

Quick matrix Block routes `GET /block/{block_ref}``GET /block/{number}/txs`Block events and receipts `GET /search`

Loading documentation content…

Route examples

Use this page when an agent needs concrete response-shape examples for routes that are easy to misuse.

Start from the published OpenAPI/docs for the host you are targeting. The bounded public route set below is the supported hosted contract. The machine-readable contract is always available at /mezcal-openapi.yaml.

Hosted base shape:

$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/...

Quick matrix

Route	Freshest?	Exact?	Paginated?	Expensive?	Best for wallet state?	Best for tx debugging?
`GET /block/{block_ref}`	block snapshot at the referenced height	yes	no	standard	no	yes
`GET /block/{number}/txs`	block snapshot at the referenced height	yes	cursor-based	standard	no	yes
`GET /search`	no	n/a	no	heavy	no	sometimes
`GET /tx/{tx_hash}/trace`	stable historical trace	n/a	no	heavy	no	yes
`GET /contract/{address}/read`	latest by default	exact spot read	no	heavy	sometimes	yes
`POST /tx/previews`	historical preview snapshot	compact by default	request-bounded batch	heavy	no	sometimes
`GET /address/{address}/transactions`	indexed transaction rows	one row per tx	cursor-based	heavy	no	sometimes
`GET /address/{address}/token-holdings`	near-latest indexed state	only when `exact=true`, `truncated=false`, and `completeness.reasonCode="complete"`	no	heavy	yes	no

Block routes

block_ref is a flexible path segment. It accepts:

a block number
a block hash

If you need the current head block, read GET /v1/{chain}/status first and then call /block/{block_ref} with the returned block number or block hash.

`GET /block/{block_ref}`

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/block/8279910?tx_limit=3"

Response shape:

{
  "chainId": "SN_MAIN",
  "blockNumber": 8279910,
  "blockHash": "0x03...",
  "parentHash": "0x02...",
  "timestampIso": "2026-04-10T15:43:12Z",
  "txCount": 31,
  "finalityStatus": "ACCEPTED_ON_L1",
  "rawObjectKey": "s3://...",
  "transactions": [
    {
      "txHash": "0x0abc...",
      "txIndex": 30,
      "txCursor": "8279910:30",
      "fromAddress": "0x0123...",
      "toAddress": "0x0456...",
      "executionStatus": "SUCCEEDED",
      "finalityStatus": "ACCEPTED_ON_L1"
    }
  ]
}

Agent rules:

tx_limit only controls the preview array on the block detail response.
Use the dedicated /txs route when you need the full paginated block transaction list.
Use blockHash, not rawObjectKey, as the public identity of the block.

`GET /block/{number}/txs`

This child route is numeric-only. If you start from a block hash, resolve the canonical blockNumber first with GET /v1/{chain}/block/{block_ref}. If you need the current head block, read GET /v1/{chain}/status first and then call /block/{number}/txs with that numeric block number.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/block/8279910/txs?limit=2"

Response shape:

{
  "items": [
    {
      "txHash": "0x0abc...",
      "txIndex": 30,
      "txCursor": "8279910:30",
      "fromAddress": "0x0123...",
      "toAddress": "0x0456...",
      "executionStatus": "SUCCEEDED",
      "finalityStatus": "ACCEPTED_ON_L1"
    }
  ],
  "nextCursor": "29"
}

Agent rules:

Ordering is newest-first within the resolved block: highest txIndex to lowest.
If you need the current head block, read GET /v1/{chain}/status first and then use the returned numeric block number here.
GET /block/{number}/txs itself always uses the resolved numeric block number, including follow-up pages with cursor.
nextCursor is exclusive. Pass it back as cursor unchanged.

Block events and receipts

The bounded hosted route set does not currently publish per-block events or receipts pages.

Use these instead:

GET /v1/{chain}/block/{block_ref} for canonical block metadata
GET /v1/{chain}/block/{number}/txs for the ordered block transaction list
GET /v1/{chain}/tx/{tx_hash} for execution and finality metadata on a specific transaction
GET /v1/{chain}/tx/{tx_hash}/trace when you need deeper execution context
Resolve blockNumber first when you start from a block hash or current head metadata, then use that numeric block number for /txs pagination.
If you need logs or token transfers for a transaction, hydrate GET /tx/{tx_hash} separately.

`GET /search`

search is identifier-first. It resolves exact hashes, block numbers, and address-like inputs first, then falls back to bounded prefix search.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/search?q=0x1234"

Response shape:

{
  "blocks": [],
  "transactions": [],
  "addresses": ["0x0000000000000000000000000000000000000000000000000000000000001234"]
}

Agent rules:

q is required.
Results are split into the top-level blocks, transactions, and addresses arrays.
This route is not the place to do generic ticker or symbol discovery.

`GET /tx/{tx_hash}/trace`

This route returns a trace envelope, not a top-level calls array.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/tx/<tx_hash>/trace"

Response shape:

{
  "chainId": "SN_MAIN",
  "txHash": "0x04...",
  "trace": {
    "functionInvocations": [],
    "validateInvocation": null,
    "feeTransferInvocation": null,
    "stateDiff": null
  }
}

Agent rules:

Treat trace as the root object.
Do not assume every tx has every invocation section populated.
Use this route for execution debugging, not latest wallet state.

`GET /contract/{address}/read`

This route requires a raw Starknet selector, not a function name.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/contract/<address>/read?selector=<felt_selector>&block_tag=latest"

Response shape:

{
  "chainId": "SN_MAIN",
  "contractAddress": "0x0123...",
  "selector": "0x0456...",
  "blockTag": "latest",
  "result": ["0x417267656e744163636f756e74"]
}

Agent rules:

result is always an array of felts.
Default view tooling may decode a felt to UTF-8, but the API returns raw felt strings.
Invalid selector, wrong calldata, or non-view misuse is client error territory, not proof that the route is broken.

`POST /tx/previews`

This route is compact by default. Omitted detail must not be confused with empty detail.

Request:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/tx/previews" \
  -d '{"hashes":["0xabc"],"includeLogCounts":true}'

Response shape:

{
  "items": [
    {
      "txHash": "0xabc",
      "blockNumber": 123,
      "status": "ACCEPTED_ON_L2",
      "transfersIncluded": true,
      "logsIncluded": false,
      "logCountsIncluded": true,
      "logCount": 5,
      "logs": [],
      "logsTruncated": false
    }
  ]
}

Agent rules:

logsIncluded=false means logs=[] is omission, not evidence of no logs.
logCountsIncluded=false means logCount is not authoritative.
Use previews for lightweight batch hydration, not full forensic decoding.

`GET /address/{address}/token-holdings`

This is the screening route for wallet portfolio state, but only the completeness contract tells you whether the snapshot is authoritative. It is wallet-first indexed state, not the same thing as an on-chain balanceOf spot read.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/<owner>/token-holdings"

Response shape:

{
  "chainId": "SN_MAIN",
  "ownerAddress": "0x0abc...",
  "items": [
    {
      "tokenAddress": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "normalizedTokenAddress": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "indexedBalanceRaw": "909437023198396908352",
      "symbol": "STRK",
      "name": "Starknet Token",
      "decimals": 18
    }
  ],
  "exact": false,
  "truncated": false,
  "completeness": {
    "exact": false,
    "truncated": false,
    "complete": false,
    "reasonCode": "degradedFallback",
    "reason": "The response is useful for screening but is not complete enough for exact portfolio parity checks.",
    "lagBlocks": null,
    "capped": false,
    "cap": null
  }
}

Agent rules:

Treat the snapshot as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".
exact=false with truncated=false is valid. It means incomplete-but-not-capped, not “empty”.
Use normalizedTokenAddress, symbol, name, and decimals from the row when present. Do not infer STRK, ETH, USDC, or bridged assets from raw felts.
Compare balance-of against holdings only when you already know the token contract and the requests are close in time.
Use GET /token/{token}/balance-of/{address} for exact spot reads on a known token contract.

`GET /address/{address}/transactions`

Use this route when an agent needs recent wallet transactions as one row per tx. It avoids repeatedly grouping activity rows by txHash.

Request:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/<owner>/transactions?limit=25"

Response shape:

{
  "items": [
    {
      "blockNumber": 8279910,
      "txIndex": 30,
      "txHash": "0x0abc...",
      "kinds": ["token_in", "contract_call"],
      "counterparty": "0x0456..."
    }
  ],
  "nextCursor": "opaque-cursor-1"
}

Agent rules:

Use transactions when the unit of work is a transaction.
Use activity when the unit of work is a transfer/event-like row.
Pass nextCursor back unchanged as cursor.

When to use which route

Need	Route
typed identifier or token lookup	`GET /search`
execution tree or internal call debugging	`GET /tx/{tx_hash}/trace`
one selector against one contract	`GET /contract/{address}/read`
ordered lightweight hydration for many tx hashes	`POST /tx/previews`
recent wallet transactions, one row per tx	`GET /address/{address}/transactions`
wallet screening and current portfolio state	`GET /address/{address}/token-holdings`

If the question is “what can this deployment do?”, use the host’s published OpenAPI or docs surface first rather than probing unpublished discovery endpoints.