Agent HTTP quickstart

Give an agent a bounded Starkscan HTTP contract without making it guess base paths, auth, or route scope.

API reference Reference Quickstart TypeScript SDK

In this guide

Canonical setup One-command conformance smoke Smallest safe route set First working checks 1. Verify the host and key 2. Verify one tx detail and one tx trace

Loading documentation content…

Agent HTTP quickstart

Use this page when you are giving an agent direct Starkscan HTTP access instead of MCP or the CLI.

This page is intentionally narrower than the full API guide. It covers a bounded route set, one canonical base-path shape, and the minimum issue-report contract. Agents and SDK generators should read the host-local OpenAPI file at /mezcal-openapi.yaml before guessing query params or enums.

Canonical setup

Use one base-path pattern only:

export MEZCAL_BASE_URL="https://<your-mezcal-host>/api"
export MEZCAL_API_KEY="mzk_live_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"

Hosted requests then always look like:

$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/...

Do not paste full API keys into agent chats, tickets, screenshots, PR comments, or shared prompts. Store the key in an environment variable or secrets manager. Rotate immediately if the full value appears in chat or logs.

One-command conformance smoke

For a repo checkout, run the smoke before handing a key to an agent or after a preview deploy:

MEZCAL_BASE_URL="https://<host>/api" \
MEZCAL_API_KEY="$MEZCAL_API_KEY" \
rust-exp/scripts/agent-api-conformance-smoke.sh

The script never prints the full key. It verifies host auth, JSON error shape, request-id mirroring, status, address transactions, holdings completeness fields, token metadata fields, and the published OpenAPI error/header contract. If MEZCAL_API_KEY is unset, it still checks invalid-key behavior and OpenAPI.

Smallest safe route set

Start with the smallest route set that answers the task:

Job	Route
health / host reachability	`GET /v1/{chain}/status`
latest blocks	`GET /v1/{chain}/blocks`
one block	`GET /v1/{chain}/block/{block_ref}`
block transaction list	`GET /v1/{chain}/block/{number}/txs`
tx list scan	`GET /v1/{chain}/txs`
one tx	`GET /v1/{chain}/tx/{tx_hash}`
one tx trace	`GET /v1/{chain}/tx/{tx_hash}/trace`
compact tx batch	`POST /v1/{chain}/tx/previews` (advanced utility — needs utility key tier)
wallet activity	`GET /v1/{chain}/address/{address}/activity`
wallet transactions	`GET /v1/{chain}/address/{address}/transactions`
wallet holdings	`GET /v1/{chain}/address/{address}/token-holdings`
exact token balance	`GET /v1/{chain}/token/{token}/balance-of/{address}`
token transfer history	`GET /v1/{chain}/token/{token}/transfers`
contract read	`GET /v1/{chain}/contract/{address}/read`
contract selectors	`GET /v1/{chain}/contract/{address}/entrypoints`
identifier lookup	`GET /v1/{chain}/search`

Stay on this set unless you already know you need a published advanced utility.

First working checks

1. Verify the host and key

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/status"

2. Verify one tx detail and one tx trace

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

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

3. Verify one block path

Use block/{block_ref} when the agent starts from a block number or block hash:

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

Use child routes when the task needs canonical block contents. If you start from a block hash, resolve 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 the block route with the returned number or hash:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/block/<block_number>/txs?limit=25"

If you need per-transaction execution or receipt context for a block, walk the txs page and then read GET /v1/{chain}/tx/{tx_hash} or GET /v1/{chain}/tx/{tx_hash}/trace per transaction.

4. Verify one wallet-state path

Use token-holdings for wallet screening:

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

Use balance-of only when you already know the exact token contract:

curl \
  -H "X-Starkscan-Api-Key: $MEZCAL_API_KEY" \
  "$MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/<token>/balance-of/<owner>?block_tag=latest"

Contract caveats agents must obey

block_ref accepts a block number or block hash.
If you need the current head block, read GET /v1/{chain}/status first and then reuse the returned block number or hash.
For block/{number}/txs, use a numeric block number. If you started from a block hash, resolve blockNumber first.
Pass returned nextCursor values back unchanged. Do not build block cursors yourself.
GET /v1/{chain}/search?q=... is identifier-first search. It is not ticker or symbol search.
Treat token-holdings as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".
Read normalizedTokenAddress, symbol, name, and decimals from holdings rows when present; do not infer token identity from raw felts.
Use GET /v1/{chain}/address/{address}/transactions when the agent wants one row per tx. Use activity when it wants transfer-granular rows.
GET /v1/{chain}/contract/{address}/read requires a raw Starknet selector, not a function name.
GET /v1/{chain}/contract/{address}/entrypoints is broader than read; for read, prefer selectors with stateMutability=view and pass required calldata.
POST /v1/{chain}/tx/previews expects {"hashes":[...]}.
tx/previews is compact by default. Ask for includeLogCounts=true or includeLogs=true before you infer that logCount=0 or logs=[] means “no logs”.

If the agent still needs concrete route shapes, use Route examples before guessing response semantics.

Error contract

Status	Meaning	Client action
`401`	key missing or invalid	stop and fix auth
`403`	valid key, wrong scope or route tier	stop and fix key tier
`429`	rate limit hit for the current route class	honor `Retry-After` and back off
`503`	temporary unavailability	retry with backoff and honor `Retry-After` when present

Error responses use a JSON envelope:

{
  "code": "rate_limited",
  "message": "Rate limit exceeded; retry shortly",
  "docSlug": "api/rate-limits",
  "requestId": "mzk-..."
}

For route-class budgets and headers, see Rate limits. Agents should log X-Mezcal-Route-Class, Retry-After, and X-Request-Id when present.

Bug report template

When an agent reports a Starkscan issue, include:

exact base URL and chain
exact route and query string
request body for POST routes
auth mode used (X-Starkscan-Api-Key)
response status
response body snippet
X-Request-Id
X-Mezcal-Route-Class
relevant rate-limit headers if present
expected result
actual result

Copy-paste template:

Host:
Chain:
Route:
Query params:
Request body:
Auth mode:
Status:
X-Request-Id:
X-Mezcal-Route-Class:
Rate-limit headers:
Response snippet:
Expected:
Actual:

Use another surface when

use MCP when the client already speaks tool-calling
use the CLI when the workflow is terminal-first
use the full API guide when you need the broader public contract