Quickstart

Requires Node.js 22.13+ (or Bun 1.1+). No keys, no chain: spendctl mock verifies real EIP-712 signatures and fakes settlement.

mkdir spend-demo && cd spend-demo
npx spendctl init          # spendctl.yaml + .spendctl/ (git-ignored)
npx spendctl mock          # terminal 1: facilitator :4020, weather API :4021 (x402 v2), search API :4022 (x402 v1)
npx spendctl start         # terminal 2: the sidecar on 127.0.0.1:8402

Be the agent in a third terminal:

npx spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher
# ✔ 200 paid $0.01

Repeat it. The default policy gives researcher $0.03 per day with onBudgetExceeded: approve, so the fourth call is held until a human decides:

npx spendctl pending
npx spendctl approve --latest      # or: npx spendctl deny --latest --note "not today"

Then look at what happened:

npx spendctl budget
npx spendctl ledger
npx spendctl export --format csv --out receipts.csv
npx spendctl dashboard --open

Try a refusal

npx spendctl fetch "http://localhost:4022/search?q=x402" --agent stranger     # unknown agent → refused
npx spendctl fetch "http://localhost:4021/weather" --agent researcher --dry-run   # what would happen, nothing signed

Next

• Make it real on Base Sepolia: Real payments.
• Wire up your agent: Integrations.