--- name: bsv-agent-spending description: "Design or implement an AI agent or automated tool that pays for things for a person: its own wallet and budget, limits enforced outside the agent, asking a human for anything out of scope, recording what each payment was for, reporting, and a stop control. Use when asked to 'let an agent pay', 'give the AI a budget', 'agent wallet', 'automate payments', 'agentic payments', or anything about software spending money without asking each time." --- > Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md). # Let software spend BSV on someone's behalf **Scope:** Delegated spending: setting the bounds, enforcing them, and reporting what happened to somebody who was not there. **Does NOT cover:** - The per-request payment itself: see [bsv-micropayments](../bsv-micropayments/SKILL.md) - Permissions an app asks for: see [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md) **Cross-references:** [bsv-micropayments](../bsv-micropayments/SKILL.md), [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md), [bsv-actions](../bsv-actions/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md). Every other flow in the guide has a person at the moment money moves. Here the decision was delegated and the person arrives afterwards, so the design moves from asking to bounding and reporting: what the agent may do, and what it did. On BSV, payments are small enough to be automatic and a program can hold its own keys, so this is an ordinary flow. ## ALWAYS - Fund an agent by deliberate top-up, as a human action. A standing instruction to refill is the thing that turns a bounded loss into an unbounded one. _([costs money](https://www.bitcoinsv.design/guide/rule/a96515e0c0/))_ - Enforce limits outside the agent, in the wallet or the service holding its keys. A limit the agent checks itself is a limit an injected instruction can argue with. _([costs money](https://www.bitcoinsv.design/guide/rule/63a9fc8258/))_ - Show the amount and the payee from the payment Scout's wallet refused, and Scout's explanation separately, labelled as Scout's. If the explanation names a different amount, show both and say they disagree. _([costs money](https://www.bitcoinsv.design/guide/rule/fa105418c9/))_ - Refuse a payment above the price shown on the limits screen, even when it is inside the per-payment limit, and send it to Anna like any other request outside scope. _([costs money](https://www.bitcoinsv.design/guide/rule/23eeedf9ef/))_ - Cap paid retries to one service at a fixed number per task, show that number on the limits screen, and stop using the service when it is reached. Each retry is another payment, and a loop of small failures is how an agent spends its budget on nothing. _([costs money](https://www.bitcoinsv.design/guide/rule/5b82904b28/))_ - Make pausing take effect in Scout's wallet, not in the assistant. Spending stops even if the assistant is still running or has not noticed. _([costs money](https://www.bitcoinsv.design/guide/rule/35dd3d1ba8/))_ ## NEVER - Hand an agent the user's identity key or their Passes. It can have its own identity and act as itself; it should never be able to prove it is the person. _([costs money](https://www.bitcoinsv.design/guide/rule/a4ece91f55/))_ - Put "Always allow" or "Add to Scout's services" on the approval screen. Widening Scout's scope from a notification is how one odd request becomes a standing permission. _([costs money](https://www.bitcoinsv.design/guide/rule/44db19b4c1/))_ - Let the assistant approve its own request, or accept an approval from anywhere other than Anna's own device. _([costs money](https://www.bitcoinsv.design/guide/rule/54786d4a9a/))_ - Let the everyday wallet draw from savings on its own. A compromised app could then drain both. _([costs money](https://www.bitcoinsv.design/guide/rule/e9ca132d95/))_ - Give an agent wallet access to savings, the owner's identity key or Passes, or the ability to reveal key linkage. _([costs money](https://www.bitcoinsv.design/guide/rule/9e9222d5c4/))_ - Report agent spending only in a log. A log is for after somebody already suspects something. _([costs trust](https://www.bitcoinsv.design/guide/rule/74988614f8/))_ ## Patterns _Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._ ### 1. Give the agent its own wallet **When:** Before the agent spends anything. It is the most important decision and it is architectural, not visual. **How:** 1. Separate keys, identity, storage and funds; not a separate basket in the user's main wallet. A budget is then a balance rather than a policy. 2. A fixed maximum balance, limits per payment, per hour and per day, approved protocols and recipients only, and permissions that expire. 3. Never the owner's identity key or Passes, never access to savings, never the ability to reveal key linkage or change its own limits. 4. Fund it by a deliberate human top-up. A standing instruction to refill turns a bounded loss into an unbounded one. _Source: [Wallet setups](https://www.bitcoinsv.design/guide/how-it-works/wallet-setups/)_ ### 2. Enforce limits where the agent cannot reach **When:** Any limit you intend to hold. **How:** 1. Enforce limits in the wallet or the service holding the agent's keys. "Don't spend more than 1,000 sats" in a prompt is an instruction, not a control, and an injected instruction can argue with it. 2. Require a human for anything out of scope: a new payee, a larger amount, a wider permission. Push it to them; do not leave it in a queue they have to look for. _Source: [Letting an agent spend](https://www.bitcoinsv.design/guide/patterns/letting-an-agent-spend/)_ ### 3. Record why, and report like a person reads **When:** Every payment the agent makes, and every summary of them. **How:** 1. Record what each payment was for at the moment it happens, in the action's `description` and `labels` (for example the task name). Intent cannot be reconstructed afterwards. 2. Show the status as current values on one screen: "412 of 5,000 sats, 18 payments today, 3 services, 22 days left". 3. Group by purpose, not by payment, and surface the unusual first: a new payee, a larger-than-usual payment. Report on a human schedule; a daily summary beats a feed nobody watches. 4. Name the agent and its purpose wherever its spending appears. Never report agent spending only in a log. _Source: [Letting an agent spend](https://www.bitcoinsv.design/guide/patterns/letting-an-agent-spend/)_ ### 4. One control that stops everything **When:** Always visible wherever the agent is. **How:** 1. One action, no confirmation step. Stopping is not an action anybody regrets. 2. Say what stopping means: no further payments, work in progress abandoned, funds stay where they are. _Source: [Letting an agent spend](https://www.bitcoinsv.design/guide/patterns/letting-an-agent-spend/)_ ## All the rules `references/rules.md`: 59 rules from 6 pages, 27 of them costly, most costly first. Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json ## Implementation resources - **[WalletPermissionsManager (Wallet Toolbox)](https://github.com/bsv-blockchain/wallet-toolbox)**: For wallet builders: per-app, per-protocol permission control with grouped approval flows. Limits enforced here are enforced by the wallet, outside anything an app or agent can change. - **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk. - **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app. - **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number. --- _Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._