Agents

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

Starkscan currently exposes three 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 without MCP
• CLI path: @starkscan/cli resolves to 0.1.2 on the default npm channel and is best for Codex, Claude Code, and local shell workflows
• MCP path: hosted MCP HTTP is still an API-key beta; @starkscan/mcp resolves to 0.1.2 for local clients that speak the Model Context Protocol

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
3. Then move to MCP quickstart if you need remote agent access

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. let the client run npx -y @starkscan/mcp

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"

Working MCP config snippet

If your agent client wants a JSON config instead of a one-shot command, this is the minimum useful shape:

{
  "mcpServers": {
    "starkscan": {
      "command": "npx",
      "args": ["-y", "@starkscan/mcp"],
      "env": {
        "STARKSCAN_API_KEY": "${STARKSCAN_API_KEY}",
        "STARKSCAN_CHAIN": "SN_MAIN"
      }
    }
  }
}

That is the practical parent-page answer for Claude Code, Codex-adjacent setups, Cursor-like MCP clients, and other tool-calling environments.

Best first tools

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

• status
• block_detail
• block_transactions
• token_total_supply
• token_balance_of
• 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 three 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
• MCP is the structured remote contract for tool-calling clients

That separation is intentional. It keeps direct HTTP agents on a bounded contract, keeps the local developer flow fast, and gives remote tool-calling clients a safer, more explicit auth and policy boundary.

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.
• Use the CLI when you need explicit commands or local exports more than tool calls.
• Stay in the explorer app when the job is visual investigation rather than automation.