Agent CLI

Use the Starkscan CLI for shell workflows, release validation, and local-first exports.

In this guide

Use this surface for When not to start here Try in app before you script it Install with npm or npx Pinned fallback Environment

Loading documentation content…

Agent CLI

Use the CLI when you need reproducible shell commands, local-first exports, or an operator-friendly surface that sits on top of the same Starkscan API contract.

Before using the CLI in unattended workflows, check the Launch matrix for the current release state and manual blockers. For npm package provenance, Socket links, and exact-version pinning rules, use Package trust.

Use this surface for

shell workflows with explicit commands and outputs
local transfer exports and privacy-sensitive analysis
release validation from a terminal
preparing the same binary for stdio MCP in Codex or Claude Code

When not to start here

Use the REST API first when you need zero-install integration.
Use the SDK when you are writing app code.
Use MCP when the consumer is already an MCP client.

Try in app before you script it

The explorer is still the fastest way to understand the data you are about to automate:

Dashboard for top-level chain state
Transactions for rows and detail pages
Contracts for contract metadata and activity
Watchlist for repeat address analysis

Install with npm or npx

Install the @alpha channel (or pin an exact 0.1.0-alpha.x) as shown. An untagged npm install -g @starkscan/cli resolves to a fail-closed placeholder — always include the channel tag or an exact version.

npm install -g @starkscan/cli@alpha
starkscan doctor

For a one-off agent run without a global install:

npx @starkscan/cli@alpha doctor

The npm launcher uses native CLI artifacts bundled in the published package when available, verifies archives against the bundled release manifest, caches the native Starkscan binary, and forwards all arguments to it. It does not require Rust or repository access.

For MCP clients, prefer the dedicated MCP launcher. It delegates to the same CLI package underneath but keeps onboarding stable for MCP hosts:

npx -y @starkscan/mcp@alpha print-config --transport remote
npx -y @starkscan/mcp@alpha

print-config emits JSON with environment-variable placeholders, so keep API keys in your shell or agent secret store instead of pasting literal keys into client config files.

The public alpha package and command are @starkscan/cli and starkscan.

Pinned fallback

Public beta users should use npm or npx. Maintainer-only native artifact and source-install fallbacks are intentionally kept out of the public beta docs so external agents do not depend on repository internals.

Environment

export STARKSCAN_BASE_URL="https://<your-starkscan-host>/api"
export STARKSCAN_API_KEY="mzk_live_your_key_here"
export STARKSCAN_CHAIN="SN_MAIN"

For hosted external access, keep STARKSCAN_BASE_URL on the deployment's /api base. The CLI then calls the normal /v1/* routes underneath that base for you. The CLI sends X-Starkscan-Api-Key for hosted API auth. Use STARKSCAN_* env names for new beta clients; old internal names are compatibility aliases.

If you need a pinned native release instead of npm, use the maintainer release runbook for the matching Starkscan tag. External beta clients should not need repository access.

First successful commands

starkscan status

starkscan address-activity 0xwallet --limit 50
starkscan tx-details 0xtxA 0xtxB --log-limit-per-tx 32
starkscan contract-events 0xcontract --topic0 0x... --from-block 7800000 --limit 100
starkscan contract-entrypoints 0xtoken
starkscan contract-read 0xtoken --selector balanceOf --calldata 0xwallet
starkscan token-total-supply 0x0123...
starkscan token-balance-of <ownerAddress> <tokenAddress> --block-tag pending

starkscan token-balance-of intentionally keeps the owner-first CLI order for shell readability. The REST API and SDK remain token-first, so translate it as:

CLI: starkscan token-balance-of <ownerAddress> <tokenAddress>
REST: GET $STARKSCAN_BASE_URL/v1/$STARKSCAN_CHAIN/token/<tokenAddress>/balance-of/<ownerAddress>
SDK: starkscan.tokenBalanceOf(tokenAddress, ownerAddress)

Use that command only when you already know the exact token contract you want. If the workflow is "does this wallet already hold USDC?" or "skip wallets with any nonzero holdings," prefer:

CLI: starkscan address-token-holdings <ownerAddress>
REST: GET $STARKSCAN_BASE_URL/v1/$STARKSCAN_CHAIN/address/<ownerAddress>/token-holdings

That matters on Starknet because a symbol such as USDC can map to more than one live contract or alias. An exact-token balance-of can return 0 for one USDC contract while the wallet still holds another USDC variant.

If your key class includes holdings access, add:

starkscan address-token-holdings 0xwallet

For large wallet-screening jobs, use address-token-holdings rather than looping token-balance-of for every wallet. Before you make a definitive skip/allow decision from that response, check the holdings completeness flags. Treat the result as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".

General shell workflows

starkscan block 7800000
starkscan tx 0x1234abcd
starkscan tx-details 0x1234abcd 0x5678ef90 --log-limit-per-tx 32
starkscan search 0x1234abcd
starkscan address-activity 0xwallet --limit 50
starkscan address-transactions 0xwallet --limit 50
starkscan contract-events 0xcontract --topic0 0x... --from-block 7800000 --limit 100
starkscan contract-entrypoints 0xtoken
starkscan contract-read 0xtoken --selector balanceOf --calldata 0xwallet
starkscan feed --max-events 10

Local-first transfer exports

starkscan --output-format json token-transfers 0x0123... \
  --address 0x0456... \
  --address 0x0789... \
  --from-block 7800000 \
  --to-block 7802500 > transfers.json

That gives you a narrow token + address(es) + block range export directly on your machine instead of in a shared dump.

For multi-wallet monitoring without a block range, repeat --address the same way:

starkscan token-transfers 0x0123... \
  --address 0xwalletA \
  --address 0xwalletB \
  --limit 100

For the full external starter, including the matching REST and SDK flows plus the shared env contract, use Monitor 10 wallets.

Contract event indexers

starkscan --output-format json contract-events 0xcontract \
  --topic0 0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9 \
  --from-block 7800000 \
  --to-block 7800500 \
  --limit 100

Use contract-events when you need the canonical paginated log stream for one contract before applying protocol-specific decoding. Keep filters server-side first: contract address, exact topic0..topic3, block range, then continue with --cursor.

Batch transaction hydration

starkscan --output-format json tx-details \
  0xabc... \
  0xdef... \
  --log-limit-per-tx 32

Use tx-details when you already have an ordered tx hash list and want bounded Starkscan transaction previews in one batch. Check logsTruncated and tokenTransfersTruncated before treating child arrays as exhaustive. Logs are included by default for this convenience command; pass --no-include-logs when you only need compact preview rows.

Smoke-test the CLI path

STARKSCAN_BASE_URL="https://<your-starkscan-host>/api" \
STARKSCAN_API_KEY="$STARKSCAN_API_KEY" \
./rust-exp/scripts/release-cli-smoke.sh

It validates the commands most release users rely on first:

starkscan status
starkscan block <head>
starkscan tx <sample>
starkscan search <sample>

When to choose another surface

Use the SDK for app code.
Use the REST API for raw HTTP contract debugging.
Use MCP when an agent needs tool calls rather than explicit commands.
Stay in the explorer app when the job is visual investigation instead of automation.