Agents

Use the Agents lane when a human or model is operating Starkscan through tools instead of raw REST requests.

Starkscan exposes two agent-facing paths:

• bounded HTTP path: REST core routes are certified and best when a coding agent should stay on a fixed published route set
• CLI path: @starkscan/cli is registry-authoritative; resolve and pin an exact version for unattended use. The current worker-parity, dependency-material normalization, quota-recovery, and custom-CA target is 0.5.7; require its dist-tag and hosted verification smoke before relying on locked Git workspaces with scripts, plugin permission, development-only dependencies, unrelated test members, custom TLS roots, or daily-quota recovery guidance. The CLI is best for Codex, Claude Code, and local shell workflows

Recommended order

1. Start with Agent HTTP quickstart if the agent will make direct HTTP requests
2. Start with the CLI guide if you control the local shell

First working setup

For most agent users, the shortest path is:

1. keep one Starkscan API key in the agent secret store
2. use the hosted default https://api.starkscan.co host
3. run npx -y @starkscan/cli init --agent when you want setup commands

Shared environment:

export STARKSCAN_API_KEY="YOUR_STARKSCAN_API_KEY"
export STARKSCAN_CHAIN="SN_MAIN"
# Optional: only set this for preview or self-hosted hosts.
# export STARKSCAN_BASE_URL="https://preview.example.com"

Best first commands

When you are replacing lightweight chain reads with an agent, start with:

• starkscan status
• starkscan block
• starkscan tx
• starkscan token-total-supply
• starkscan token-balance-of
• starkscan token-transfers

Those give the agent a narrow, typed Starkscan surface before it starts guessing at raw chain structure. For direct HTTP agents, the broader block route set is GET /v1/{chain}/block/{number_or_hash} for canonical block detail and GET /v1/{chain}/block/{number}/txs for the ordered block transaction list after you resolve a numeric block number. The {number_or_hash} placeholder here means block number or block hash. If you need the current head block, fetch GET /v1/{chain}/status first and then call /block/{number_or_hash} with the returned block number or block hash.

Why two paths exist

They solve different problems:

• bounded HTTP is the safest path when an agent should stay on a fixed published route set
• CLI is the fastest and simplest path for power users, local exports, and deterministic terminal workflows

That separation is intentional. It keeps direct HTTP agents on a bounded contract and keeps the local developer flow fast.

When not to start here

• Use Agent HTTP quickstart when the client should call the published REST surface directly.
• Use the REST API for direct service integrations.
• Use the SDK for typed application code.
• Stay in the explorer app when the job is visual investigation rather than automation.