npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

spendctl

v0.10.0

Published

A corporate card and expense policy for AI agents: budgets, approvals and receipts for x402, MPP and any HTTP 402 API.

Readme


  • What it is: a local sidecar your agents send HTTP requests through. When a seller answers 402 Payment Required (x402, MPP), spendctl checks the agent's policy, asks a human if needed, signs with your wallet, and writes the receipt to a ledger.
  • Why it exists: agents can now pay per request, but the protocols leave buyer-side budgets to "the implementation", the SDK guardrails run inside the agent's own process, and wallet vendors only govern the wallet they hold. Per-agent caps are free everywhere; what is missing is one policy, one approval flow and one ledger across all of them.
  • What you get: per-agent budgets (per request / hour / day / week / month), host allowlists, recipient pinning, approval thresholds, price-jump and first-payment checks, agent→agent chain limits, dry-run, CSV/JSON export, MCP tools, a dashboard. Non-custodial: signing happens in the sidecar you run, against a wallet you own — a Coinbase CDP server wallet or your own key. spendctl never holds keys or funds.

Why a sidecar

"Hard limits (validation, approval gates) and anything else that comes up mid-conversation (e.g. memory lookup) move into the tools." — Anthropic, Building agents: When to fold subagents into your main agent loop

spendctl is that tool for money. The agent can be talked into asking. It cannot be talked into paying. The key, the policy and the ledger live in a separate process the model cannot edit; refusals come back as plain sentences the model can read.

Where spendctl fits:

| | Where it runs | Per-payment cap | Time-window budgets | Human approval | Exportable ledger | Host/endpoint budgets + price pinning | Your wallet, your sidecar (non-custodial) | Wallet- & protocol-neutral | |---|---|---|---|---|---|---|---|---| | x402 SDK spendControls (@x402/core 2.30) | inside the agent | ✓ ($1 default) | — | hook only | — | — | your wallet, in-process | x402 only | | CDP SDK x402 spend controls (≥ 1.53) | inside the agent | ✓ | ✓ rolling, in-memory by default | — | — | — | CDP wallet, in-process | CDP + x402 | | Wallet-bundled caps (Coinbase Agentic Wallet, AWS AgentCore payments) | wallet UI / Bedrock | ✓ free | per session | — | some | — | one or two wallet providers | their rails | | Wallet policy engines (Privy, Turnkey, Circle, CDP Policies…) | wallet vendor | ✓ | some | some | some | — | their wallet | own keys only | | Hosted agent-payment platforms (Catena, Locus, xpay, Nevermined…) | their cloud | ✓ | ✓ | some | ✓ | some | their wallet or proxy | their rails | | spendctl | your sidecar | ✓ | ✓ per agent | ✓ CLI / webhook / link | ✓ CSV / JSON | ✓ + payee pinning, price-jump | ✓ any signer you already have | ✓ any EVM signer; x402 v1/v2, MPP |

Hosted platforms govern the wallet they hold; spendctl governs the wallets you already have — one policy, one approval flow and one ledger in front of whichever wallet and payment protocol your agents meet. The x402 v2 spec lists "Client-side budget management" as out of scope, and builders are hitting it: x402#3703 (a cumulative budget can't be built correctly on the client hooks), x402#3866 (the official client paid a server that inflated its price ×10).

Quickstart (5 minutes, no keys, no chain)

Requires Node.js 22.13+ (or Bun 1.1+).

mkdir spend-demo && cd spend-demo
npx spendctl init                 # writes spendctl.yaml + .spendctl/ (git-ignored)
npx spendctl mock                 # terminal 1: mock facilitator + two paid APIs
npx spendctl start                # terminal 2: the sidecar on 127.0.0.1:8402

In a third terminal, be the agent:

npx spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher
# ✔ 200 paid $0.01
npx spendctl fetch "http://localhost:4021/weather?city=Tokyo" --agent researcher   # 2nd, 3rd …
# the 4th call exceeds the $0.03/day budget → it waits for a human (terminal 2 prints the approval id).
# Decide from a fourth terminal; the waiting fetch then completes:
npx spendctl pending
npx spendctl approve --latest
npx spendctl ledger
npx spendctl export --format csv --out receipts.csv

spendctl mock never touches a chain: its facilitator verifies real EIP-712 signatures and fakes settlement. When you're ready for testnet money, see Real payments. Full walkthrough: spendctl.dev/docs/quickstart.

No install at all: connect the hosted sandbox https://mcp.spendctl.dev/mcp from Claude, Claude Code, Cursor or VS Code and let the model drive a real sidecar against mock paid APIs — no login, no funds. See spendctl.dev/docs/sandbox.

The policy

# spendctl.yaml
version: 1
signer:
  type: cdp                      # Coinbase CDP server wallet: keys stay in CDP

approvals:
  timeout: 10m                   # nobody answered → denied
  webhooks:
    - url: https://hooks.slack.com/services/T000/B000/XXXX
      format: slack              # json | slack | discord (HMAC-signed with secretEnv)

defaults:
  networks: ["eip155:84532"]     # Base Sepolia only until you opt in
  assets: ["USDC"]
  maxChainDepth: 3               # agent → agent → agent, then stop
  priceJumpFactor: 3             # >3× the last price paid for an endpoint → human
  firstPaymentMax: "0.05"        # first payment to a new recipient above this → human

agents:
  researcher:
    budget: { perRequest: "0.05", daily: "1.00", monthly: "20.00" }
    onBudgetExceeded: approve    # deny | approve
    requireApprovalAbove: "0.50"
    allow: ["api.weather.dev", "*.search.dev/v1/*"]
    deny: ["*.casino.example"]
    payTo:
      "api.weather.dev": ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"]   # refuse recipient swaps

Every rule fails closed: unknown agent, unknown asset, unsupported scheme or flow → denied, with a reason.

How it works

sequenceDiagram
    participant A as Agent (no keys)
    participant S as spendctl sidecar
    participant H as Human
    participant API as Paid API
    A->>S: GET https://api.weather.dev/forecast
    S->>API: GET /forecast
    API-->>S: 402 + payment requirements (x402 v1/v2 or MPP)
    S->>S: policy: allowlist, budgets, payee, price, chain depth
    alt over a limit with onBudgetExceeded: approve
        S->>H: webhook / CLI / review link
        H->>S: spendctl approve apr_…
    end
    S->>S: reserve budget (SQLite BEGIN IMMEDIATE), sign once
    S->>API: GET /forecast + payment header
    API-->>S: 200 + settlement (tx hash)
    S-->>A: 200 response + x-spendctl-* headers

The payment path stays in your network. With a Pro or Team key the sidecar syncs one policy from the spendctl control plane and can keep a hosted copy of its ledger there (both live); approvals through the control plane are in development. There is no round trip to us on the payment path, and the hosted service never relays a signature.

What is guaranteed

Each rule has an end-to-end scenario that runs real HTTP servers (mock sellers, mock facilitator, sidecar). Every scenario runs twice on every CI run.

| # | Rule | |---|---| | S01 | A payment inside every limit is signed once, settled, and recorded with its tx hash. | | S02 | Spending exactly up to the daily budget is allowed. | | S03 | A payment that would exceed a budget is never signed. | | S04 | Over-budget spend with onBudgetExceeded: approve waits for a human and pays only after approval. | | S05 | If nobody approves in time, the payment is denied. | | S06 | Hosts outside the allowlist are never paid. | | S07 | When a recipient is pinned for a host, a 402 naming another recipient is refused. | | S08 | A seller that suddenly inflates its price (×10, as in x402#3866) needs a human before it is paid. | | S09 | An agent cannot attach or replay a payment header itself; only spendctl signs. | | S10 | A retried request with the same Idempotency-Key is not paid twice. | | S11 | Payments deeper than maxChainDepth in an agent→agent chain are refused; parents are recorded. | | S12 | When settlement fails, spendctl never retries a signed payment and stops paying that host (circuit breaker). | | S13 | A payment the seller could not settle consumes budget only until the authorization signed for it expires. | | S14 | Concurrent requests can never overspend a budget, not even by one payment. | | S15 | Dry-run records the decision and never signs. | | S16 | An agent cannot approve its own payment; approvals need the admin token. | | S17 | Agents that are not in the policy cannot spend. | | S18 | Only allowed networks and assets are paid; the cheapest acceptable option is chosen. | | S19 | Schemes spendctl cannot budget safely (e.g. upto) are refused with a readable reason. | | S20 | An approval pays exactly the recipient, network, asset and amount the human saw; a retry offering anything else is refused. | | S21 | A seller that raises its price a little at a time cannot take more than its endpointBudget from an agent; the agent's other endpoints keep working. | | S22 | An agent can withdraw a held payment its task no longer needs; a late approve pays nothing and a retry with that id is evaluated afresh. |

Integrations

| How your agent talks to spendctl | Use it when | |---|---| | Gateway URL — http://127.0.0.1:8402/https://api.example.com/path + X-Spendctl-Agent | any language, any HTTP client | | wrapFetch() from @spendctl/client (Apache-2.0) | TypeScript/JavaScript agents (zero dependencies) | | MCP server — spendctl mcp (tools pay, await_approval, withdraw_approval, check_budget, list_receipts) | Claude Code, Claude Desktop, Cursor, any MCP client | | spendctl run --agent A -- <cmd> — sets HTTP_PROXY | plain-HTTP tools; HTTPS is tunnelled unpaid (use the gateway for paid HTTPS) |

Framework guides with complete programs, typechecked against the real SDKs: Claude Agent SDK, OpenAI Agents SDK, LangGraph.

import { wrapFetch, readRefusal } from "@spendctl/client";

const pay = wrapFetch({ agent: "researcher" });        // talks to the sidecar, holds no keys
const res = await pay("https://api.weather.dev/forecast?city=Tokyo");
const refusal = await readRefusal(res);                 // { error, message, approval?, reasons }

MCP (Claude Code):

claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcp

Protocols: x402 v1 and v2 (exact on EVM — Base, Base Sepolia, any EIP-3009 token), MPP (charge intent via a pluggable credential provider; parsing, policy and receipts today, no live MPP payment yet).

Real payments (Base Sepolia)

npm install spendctl @coinbase/cdp-sdk   # the CDP SDK is an optional peer of spendctl: install both in your project
npx spendctl init --signer cdp --force   # then fill .env (see .env.example)
npx spendctl wallet fund                 # 1 testnet USDC from the CDP faucet
npx spendctl start

The CDP server wallet signs EIP-712 authorizations; the private key never exists in your process. A live run against the official @x402/hono middleware and the public x402.org facilitator is documented at spendctl.dev/docs/real-payments (tx on BaseScan).

Commands

spendctl init | start [--dry-run] | mock
spendctl fetch <url> --agent A [--dry-run] | run --agent A -- <cmd> | mcp | token <agent>
spendctl pending | approve <id>|--latest|--all | deny <id>
spendctl budget | ledger | export --format csv|json | trace <id> | resolve <id> --settled|--failed
spendctl dashboard [--open] | wallet [address|fund] | license [set <key> | remove]
spendctl policy [pull] | ledger sync [now]        # with a Pro or Team key

Security model

  • Agents never hold keys or the admin token. Approvals require the admin token (CLI, dashboard) or an HMAC-bound review link that only acts on POST.
  • Budgets are reserved inside SQLite BEGIN IMMEDIATE transactions before signing; failed settlements release them; unknown outcomes count until reconciled.
  • The ledger stores no headers or bodies and drops query strings.
  • The sidecar binds to 127.0.0.1. Run agents as a different OS user (or container) if they have shell access, so they can't read .spendctl/admin.token.

Full security model and threat notes: spendctl.dev/docs/security. Report vulnerabilities to [email protected].

Pricing

Every enforcement feature above is in the Free tier. Paid tiers add the spendctl control plane — policy sync across sidecars, pooled budgets, Slack/Discord approvals, SSO/RBAC, hosted ledger retention and a fleet dashboard — still non-custodial. The control plane is in development; Pro and Team are founding pre-orders until it ships, and the Enterprise row is on the same timeline. The sidecar enforces the Free limits itself — 2 agents, checked at spendctl start, and 1,000 governed payments per month; refusals and the mock sandbox never count — and reads a licence key for Pro and Team (how it works).

| Tier | Price | Includes | |---|---|---| | Free | $0, no card | 2 agents, 1 policy, 1,000 governed payments/month, local ledger + CSV/JSON export, CLI/webhook approvals, 1 seat, local sandbox | | Pro | $29/mo (founding $19) | 10 agents, 25k governed payments/month, 90-day hosted ledger, Slack/Discord approvals, scheduled exports + accounting templates, 3 seats | | Team | $249/mo (founding $149) | unlimited agents, 500k governed payments/month, 1-year immutable ledger, SSO/RBAC, pooled budgets, chain trace across sidecars, policy-as-code CI, region pinning (US/EU/JP) | | Enterprise | contact us | SIEM export, SCIM, custom retention (up to 7 years), private control plane, four-eyes approvals, SLA |

From control-plane GA: overage $5 per 100k governed payments (Pro, Team) and a 14-day Team trial without a card. Founding members: the first 100, price locked for 12 months from GA. No percentage of spend, ever. Pricing →

Community: the spendctl Discord is open to everyone; Pro and up get the member channels.

Status

v0.10.0 — early. If you run 0.9.0 or earlier with real funds, upgrade: up to 0.9.0 a seller could write an x402 quote so that the amount signed was not the amount the policy evaluated; 0.9.1 and later sign only what was evaluated and check the signature before it is sent. Tested: unit and integration tests, golden scenarios (22 × 2), one live Base Sepolia payment. Not yet: Solana signing, upto/batch-settlement schemes, live MPP payments, HTTPS interception for HTTP_PROXY mode, and the paid control-plane features (in development; licence keys, check-in, the organisation portal, policy sync and the hosted ledger are live). Docs: spendctl.dev/docs.

License

spendctl — the sidecar, CLI and MCP server published on npm — is proprietary software, distributed as bundled JavaScript under its own licence terms; there is no public source repository for it. The thin client @spendctl/client is Apache-2.0 and lives at github.com/miraistudio/spendctl-sdk. © Mirai Studio, Inc. (株式会社みらいスタジオ), Tokyo.