# FAQ

> Short answers about spendctl. What it is, how an AI agent's payments are limited and approved, which protocols and frameworks it works with, what the plans include and what data leaves your machine.

Source: https://spendctl.dev/docs/faq/ (spendctl documentation; index of all pages at https://spendctl.dev/llms.txt)

Short answers, each with a link to the page that has the detail. If yours is not here, ask in the [Discord](https://discord.gg/XpraJzK8E4) or write to support@spendctl.dev.

## The basics

### What is spendctl?

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?](https://spendctl.dev/docs/).

### 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?

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](https://spendctl.dev/docs/sandbox/) has the one-line setup for each client.

### How do I run it locally?

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](https://spendctl.dev/docs/quickstart/) takes about five minutes; there is also a [Docker image](https://spendctl.dev/docs/docker/).

### 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](https://spendctl.dev/docs/real-payments/) walks through a testnet payment with a Coinbase CDP server wallet.

## Controlling what an agent spends

### 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](https://spendctl.dev/docs/agent-budgets/) shows a complete file.

### 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).

### Can an agent approve its own payment?

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](https://spendctl.dev/docs/approvals/).

### 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?

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](https://spendctl.dev/docs/ledger/).

### 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](https://spendctl.dev/docs/policy/).

### How does a human approve a payment?

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.

## Protocols and integrations

### 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](https://spendctl.dev/docs/how-agents-pay/) explains both protocols.

### 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?

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](https://spendctl.dev/docs/langgraph/), [OpenAI Agents SDK](https://spendctl.dev/docs/openai-agents/), [Claude Agent SDK](https://spendctl.dev/docs/claude-agent-sdk/), and the rest on [Integrations](https://spendctl.dev/docs/integrations/).

### Is there a Python client?

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?

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](https://spendctl.dev/docs/spend-controls-compared/) compares them.

## Plans and data

### What does the Free tier include?

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.

### What is a governed payment?

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](https://spendctl.dev/docs/plans/).

### What do Pro and Team add today?

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](https://spendctl.dev/#pricing) shows the current offer.

### What does the sidecar send to spendctl?

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](https://spendctl.dev/docs/plans/#version-check)). [Plans and licence keys](https://spendctl.dev/docs/plans/#what-a-licensed-sidecar-sends) and the [privacy policy](https://spendctl.dev/docs/privacy/) list everything.

### 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.

### What licence is spendctl under?

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](https://github.com/miraistudio/spendctl-sdk).

### 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`.

### Where do I report a security issue?

Privately, to security@spendctl.dev. The [Security model](https://spendctl.dev/docs/security/) lists what spendctl protects against and what it does not, and [Trust](https://spendctl.dev/docs/trust/) covers where data lives and who processes it.
