Skip to content

FAQ

Short answers, each with a link to the page that has the detail. If yours is not here, ask in the Discord or write to support@spendctl.dev.

spendctl (spendctl.dev, npx spendctl on npm) is a spend-policy sidecar for AI agents that pay for APIs over HTTP 402. The agent sends its requests through the sidecar. When a seller asks for payment, spendctl checks the request against a policy file: budgets per agent, allowed hosts, pinned recipients, an approval threshold. It then pays, refuses with a reason the model can read, or holds the payment for a human, and it records every attempt in a ledger. See What is spendctl?.

Is spendctl a wallet or a payment processor?

Section titled “Is spendctl a wallet or a payment processor?”

No. 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; money moves from your wallet straight to the seller. The hosted control plane stores policies, ledger rows and approvals, never keys or funds, and never relays a signature.

How do I try it without installing anything?

Section titled “How do I try it without installing anything?”

Connect an MCP client (Claude, Claude Code, Cursor, VS Code) to the hosted sandbox at https://mcp.spendctl.dev/mcp. It runs a real sidecar against mock paid APIs with mock money, and needs no login. Sandbox has the one-line setup for each client.

With Node.js 22.13 or later: npx spendctl init, then npx spendctl mock and npx spendctl start in two terminals. The bundled mock facilitator means no keys and no chain are needed. The Quickstart takes about five minutes; there is also a Docker image.

Do I need crypto, a wallet or an API key to try it?

Section titled “Do I need crypto, a wallet or an API key to try it?”

No. The sandbox and the local quickstart both use a mock signer and mock sellers. A real wallet is only needed for real payments; Real payments walks through a testnet payment with a Coinbase CDP server wallet.

How do I stop an AI agent from overspending?

Section titled “How do I stop an AI agent from overspending?”

Put the limit where the agent cannot reach it. In spendctl that is spendctl.yaml: a cap per request, budgets per hour, day, week and month, budgets per seller, a list of hosts the agent may pay and an amount above which a human must approve. The sidecar enforces it in a separate process, so a prompt cannot change it. Budgets for AI agents shows a complete file.

What happens when an agent reaches its budget?

Section titled “What happens when an agent reaches its budget?”

You choose with onBudgetExceeded. With deny (the default) the request is refused with HTTP 402, the error spendctl_denied and a reason such as daily_exceeded, and nothing is signed. With approve the payment is held for a human, and nothing is signed while it waits. An unanswered approval is denied after approvals.timeout (10 minutes by default).

No. Every decision needs the admin token, which lives in a file the agent is never given. Review links are bound to that token and only act on a button press, so a chat app that previews the link approves nothing. An approval is also bound to the recipient, network, asset and amount the human saw: if the seller’s terms change on the retry, it is refused with approval_mismatch. See Approvals.

Can a prompt injection make the agent pay?

Section titled “Can a prompt injection make the agent pay?”

It can make the agent ask. It cannot change the answer. Budgets, allowed hosts, recipient pins and approval thresholds live in a policy file the model cannot edit, evaluated in a separate process. Refusals come back as plain sentences, so the model can explain them instead of retrying in a loop.

Can an agent pay twice for the same request?

Section titled “Can an agent pay twice for the same request?”

spendctl signs at most once per decision and never re-sends a signed payment after a failure. A retry carrying the same Idempotency-Key within the window (10 minutes by default) is refused with duplicate_request. A payment whose outcome could not be confirmed is marked unknown and keeps counting against the budget until a human reconciles it. See Ledger and reconciliation.

What if a seller swaps the recipient or raises the price?

Section titled “What if a seller swaps the recipient or raises the price?”

Policy is checked against the host the agent actually called, never a URL the 402 claims. payTo pins the recipient, and optionally the network and asset, per host. firstPaymentMax holds a large first payment to a new recipient for a human, and priceJumpFactor holds a price above N times the last one paid for that endpoint. See the Policy reference.

From the CLI (spendctl pending, spendctl approve, spendctl deny), from the local dashboard, or from a review link delivered by webhook to Slack, Discord or any JSON endpoint. The request shows the agent, endpoint, amount, recipient and the reason it was held.

Which payment protocols does spendctl support?

Section titled “Which payment protocols does spendctl support?”

x402 v1 and v2 with the exact scheme on EVM networks, signed and settled end to end. MPP charge challenges are parsed, checked against the same policy and recorded; paying one needs a credential provider wired in code, and no live MPP payment has been made through spendctl yet. HTTP 402, x402 and MPP explains both protocols.

Which networks and assets can it pay with?

Section titled “Which networks and assets can it pay with?”

EVM networks named by CAIP-2 id, and the USD-pegged stablecoins the x402 SDK lists for each of them. The default policy allows Base Sepolia (eip155:84532) and USDC; add eip155:8453 for Base mainnet. Budgets are in USD, so an asset without a USD value is refused unless you declare it under assets:.

Does it work with LangGraph, the OpenAI Agents SDK or the Claude Agent SDK?

Section titled “Does it work with LangGraph, the OpenAI Agents SDK or the Claude Agent SDK?”

Yes. Any agent that can make an HTTP request can use the gateway URL. There is a zero-dependency fetch wrapper for TypeScript, a Python client, and an MCP server for clients that speak MCP. Worked examples: LangGraph, OpenAI Agents SDK, Claude Agent SDK, and the rest on Integrations.

Yes: pip install "spendctl-sdk[httpx]", imported as spendctl_sdk. The package named spendctl on PyPI is an unrelated project.

How is this different from the spend controls in the x402 SDK or my wallet?

Section titled “How is this different from the spend controls in the x402 SDK or my wallet?”

Use those too. The x402 client caps a single payment inside the agent’s process; a wallet’s policy engine covers the keys it holds. spendctl adds what sits across them: budgets over time, rules about hosts and recipients, human approvals and one ledger, for every agent and wallet behind the sidecar. Where spend controls can live compares them.

The full sidecar with every enforcement feature, no card: 2 agents, 1 policy and 1,000 governed payments per month, with the local ledger and CSV / JSON export. At the cap new payments are refused until the month rolls over. Nothing counts while the signer is the mock.

A request the sidecar did payment work for: it signed, or it asked a human. Refusals and dry runs never count, so an agent cannot use up the month by being refused. See Plans and licence keys.

A licence key that lifts the Free caps in the sidecar (Pro: 10 agents and 25,000 governed payments a month; Team: unlimited agents and 500,000), policy sync, which gives every keyed sidecar one spendctl.yaml from the portal (three sidecars on Pro, any number on Team), and a hosted copy of the ledger (90 days on Pro, one year on Team). Slack and Discord app approvals, scheduled exports, SSO and pooled budgets are in development. Regular prices are $29 a month for Pro and $249 a month for Team; pricing shows the current offer.

Without a licence key, nothing. With a key it checks in at start and once a day with six values: a random sidecar id, its version, the month, that month’s governed-payment count, the number of agents and the version number of the policy it runs. It also asks every five minutes whether the organisation syncs a policy. Ledger rows leave only after an owner enables the hosted ledger in the portal. Separately, from 0.10.0, a sidecar that signs real payments asks the public npm registry, not us, whether its own version is deprecated (Version check). Plans and licence keys and the privacy policy list everything.

If spendctl’s servers are down, can my agents still pay?

Section titled “If spendctl’s servers are down, can my agents still pay?”

Yes. The licence key is verified offline and the control plane is never on the payment path: when it is unreachable the sidecar keeps its current limits and policy and retries later.

The sidecar and CLI are distributed on npm under a proprietary licence. The thin clients, @spendctl/client, the Python client spendctl-sdk and the Claude Code / Cursor plugins, are Apache-2.0 and live at github.com/miraistudio/spendctl-sdk.

Is the spendctl package on PyPI the same project?

Section titled “Is the spendctl package on PyPI the same project?”

No. The PyPI and GitHub projects named spendctl are an unrelated personal-finance tool. This product is spendctl at spendctl.dev, installed with npx spendctl; its Python client is spendctl-sdk.

Privately, to security@spendctl.dev. The Security model lists what spendctl protects against and what it does not, and Trust covers where data lives and who processes it.