> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/wallet/0204.md). # Agent Allowances Ruth Heasman (Ruth Designs Digital) **Category:** wallet ## Abstract This specification defines an *agent allowance*: a sum of money that a wallet owner sets aside for an autonomous agent, which the agent can spend with its own key and the owner can take back at any time in one transaction. An allowance is held in ordinary transaction outputs under a two-branch locking script, so its limit is a property of the money itself rather than a policy enforced by software. The proposal specifies how allowances are created, delivered to the agent, spent, reported and swept; how an agent proves it acts for an owner using a BRC-52 certificate that the sweep also revokes; and how the resulting transactions form a receipt that anyone can check against block headers. It uses existing BRC-100 wallet methods and adds no new ones. It complements BRC-181, which bounds agents that spend through the owner's wallet, by covering agents that hold their own key and run elsewhere. ## Motivation AI agents increasingly spend money on behalf of people: they call paid model APIs, buy data and pay other services. Today they usually do this with a bearer credential such as an API key. A bearer credential can spend whatever the account behind it can, and revoking it means noticing a problem, finding the right dashboard and rotating the key while the agent keeps spending. The record of what the agent did is held by the party being paid. BRC-116 lets an application hold a `spendingAuthorization`, a monthly ceiling granted inside the owner's wallet. BRC-181 extends wallet enforcement to unattended agents: the owner's wallet keeps the keys for an isolated agent account and checks every agent request against a signed policy. Both assume the agent spends *through* the owner's wallet, so the wallet must be reachable and running for every payment. Many agents do not work that way. They run on servers or in the cloud, pay counterparties discovered at run time, and need to keep working while the owner's wallet is closed. An allowance covers that case. The owner moves a fixed amount into outputs that the agent can spend directly, with its own key. The agent cannot spend more than those outputs hold, whatever it does and however many sub-processes it starts, because the money is not there. The owner keeps a second spending path to the same outputs and can sweep whatever is left in a single transaction. Every payment the agent makes is a transaction, so the record of its spending is written by settlement rather than by any party to a later dispute. The aims are: 1. A worst case fixed before the agent starts: the agent can lose at most the allowance. 2. Revocation that is one owner action, not a race against a credential. 3. Attribution: payees can see that an agent acts for a specific owner, within a specific allowance. 4. A receipt for every payment that the owner holds and anyone can verify from block headers. 5. No new wallet interface methods, so any BRC-100 wallet can implement it. 6. The owner's wallet does not need to be online while the agent spends. ## Relationship to related work ### BRC-116: spending authorisations A BRC-116 `spendingAuthorization` limits how much an application may spend from the owner's wallet in a period. It governs applications the wallet is talking to. An allowance governs money that has already left the owner's main balance for an agent outside the wallet. The two compose: funding an allowance is spending by the application that requests it, and SHOULD count against that application's BRC-116 authorisation. ### BRC-181: wallet-enforced agent spend policy BRC-181 bounds an agent that spends through the owner's wallet. The wallet holds the keys for an isolated agent account and checks every `createAction` against a signed policy with per-transaction, period and lifetime caps, a destination allowlist, rate limits and circuit breakers. This specification covers the other topology, where the agent holds its own key and runs elsewhere. | | BRC-181 | This specification | | --------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- | | Who holds the spending key | the owner's wallet | the agent | | Where the agent runs | where it can reach the owner's wallet | anywhere | | Owner's wallet online for each payment | yes | no | | What bounds total loss | the isolated account balance, enforced with a signed policy | the value of the allowance outputs | | Per-transaction caps, allowlists, rate limits | yes, enforced by the owner's wallet | not by script; see below | | Revocation | wallet freeze or token revocation | one owner transaction, which also revokes the agent's certificate | | Payee can verify who the agent acts for | not defined in the current version | BRC-52 certificate (section 3.5) | | Record of spending | the wallet's audit log | Atomic BEEF receipts the owner holds and anyone can verify | Script cannot express BRC-181's finer limits, so an allowance on its own bounds only the total. The two compose: an agent wallet MAY enforce a BRC-181 policy over its own allowance outputs, giving per-transaction, rate and destination limits inside a total the owner can always take back. ### BRC-172: control without custody BRC-172 removes custody altogether: the agent holds a credential that advances a covenant whose payments are fixed in advance. Where the payment graph can be committed ahead of time it is the stronger construction. Allowances, like BRC-181, address agents that pay counterparties not known when authority is granted. ### BRC-151: risks of AI agents with human funds Section 9 of BRC-151 identifies the danger of an AI agent operating from the user's primary wallet, and of single-axis spending limits being drained by repeated small payments. An allowance moves the agent's money out of the primary wallet entirely, so the most it can lose is fixed when it is funded. ## Terminology * **Owner:** the person or organisation funding the agent. The owner's keys are held in a BRC-100 wallet (the *owner wallet*). * **Agent:** an autonomous program that spends from the allowance. The agent holds its own BRC-100 wallet (the *agent wallet*) with its own identity key. * **Allowance:** a set of allowance outputs funded by the owner for one agent and one purpose, identified by an `allowanceId`. * **Allowance output:** an output locked with the script in section 3.2. * **Revocation output:** a 1-satoshi output, spendable only by the owner, created with the allowance and referenced by the agent's certificate. * **Payee:** any party the agent pays. * **Sweep:** an owner transaction that spends all known allowance outputs and the revocation output back to the owner. * **Receipt:** an agent transaction that spends allowance outputs, delivered to the owner as Atomic BEEF (BRC-95). The key words MUST, SHOULD and MAY are used as described in RFC 2119. ## Specification ### 3.1 Keys Each allowance uses keys derived under BRC-42, with the BRC-43 protocol ID `[2, "agent allowance"]` and a key ID equal to the `allowanceId`. The `allowanceId` MUST be at least 16 random bytes, base64-encoded, and MUST NOT be reused. Both parties can compute both public keys without further communication: * **Owner allowance key:** `getPublicKey({ protocolID: [2, "agent allowance"], keyID: allowanceId, counterparty: agentIdentityKey, forSelf: true })`, called on the owner wallet. * **Agent allowance key:** the same call with `forSelf: false` on the owner wallet, or with `counterparty: ownerIdentityKey, forSelf: true` on the agent wallet. Deriving fresh keys per allowance keeps one owner's allowances from being linked to each other or to the owner's identity key on-chain. ### 3.2 Allowance output locking script ``` OP_IF OP_CHECKSIG OP_ELSE OP_CHECKSIG OP_ENDIF ``` Unlocking scripts: * Agent spend: ` OP_1` * Owner sweep: ` OP_0` Signatures use `SIGHASH_ALL | SIGHASH_FORKID` unless a payment protocol in use requires otherwise. The branch selector makes the spending party explicit on-chain, so a receipt and a sweep can be told apart without further data. An allowance MAY be split across several allowance outputs with the same locking script. Several outputs let an agent make payments in parallel without waiting for change from a previous payment. ### 3.3 Revocation output The funding transaction MUST also create one revocation output of 1 satoshi, locked so that only the owner can spend it: ``` OP_CHECKSIG ``` This outpoint is the `revocationOutpoint` of the agent's certificate (section 3.5). Because the agent cannot spend it, the owner can always revoke the certificate, even if the agent has moved the allowance outputs (section 6.2). ### 3.4 Funding and delivery The owner wallet creates the allowance with `createAction`, with the allowance outputs and the revocation output in an owner basket (BRC-46) named `agent allowances`, tagged with the `allowanceId`. Funding an allowance is spending by the requesting application, so wallets SHOULD count it towards that application's BRC-116 spending authorisation. The owner then delivers an *allowance descriptor* to the agent, over any authenticated channel, for example a BRC-103 session or a BRC-33 message relay: ```json { "version": "1.0", "allowanceId": "q8c1x3J0pZ0m3bJcVZ8m2w==", "purpose": "Competitor research", "ownerIdentityKey": "02…", "agentIdentityKey": "03…", "protocolID": [2, "agent allowance"], "outputs": [ { "outpoint": ".0", "satoshis": 12500 }, { "outpoint": ".1", "satoshis": 12500 } ], "revocationOutpoint": ".2", "beef": "", "expiresAt": "2026-10-10T00:00:00Z", "permittedPayees": ["02…", "03…"], "receiptChannel": { "type": "message-box", "recipient": "02…", "messageBox": "allowance_receipts" }, "certificate": { } } ``` The agent wallet MUST verify the funding transaction from the BEEF, check that each listed output carries the locking script of section 3.2 for the derived keys, and internalise the outputs with `internalizeAction` using basket insertion into an agent basket named `allowance`, recording the `allowanceId` in the output's custom instructions. `permittedPayees` is advisory. Script cannot restrict where an agent pays, so a conforming agent wallet SHOULD refuse payments to identity keys not on the list when it is present. ### 3.5 Agent certificate The owner issues the agent a BRC-52 certificate, created and revealed as described in BRC-53: * `certifier`: the owner's identity key * `subject`: the agent's identity key * `type`: the base64 SHA-256 of the string `agent allowance` * `revocationOutpoint`: the revocation output of section 3.3 * fields: `allowanceId`, `purpose`, `expiresAt`, and MAY include a display name for the owner A payee that authenticates the agent through BRC-103 MAY request this certificate to confirm that the agent acts for the owner and that the allowance has not been revoked. The agent reveals fields selectively under BRC-52, so a payee can learn that a valid allowance exists without learning its purpose. ### 3.6 Payments An agent pays from the allowance with any payment protocol whose transaction it constructs itself, including BRC-29 payments and the HTTP 402 profiles of BRC-105, BRC-121 and BRC-166. A conforming agent spending allowance outputs MUST: 1. Spend allowance outputs only through the agent branch. 2. Return any change to a new output with the same allowance locking script. 3. Pay network fees from the allowance. 4. Deliver the spending transaction to the owner as a receipt (section 3.7) as soon as it is broadcast. Rule 2 keeps unspent funds sweepable. It is a conformance rule rather than a script rule: section 6.2 covers agents that break it. Because an active agent repeatedly spends its own unconfirmed change, the ancestry carried in each payment's BEEF grows with each payment. Payees using BRC-105 SHOULD support the known-txids mechanism of BRC-105 section 5.3 for allowance payers. ### 3.7 Receipts For each spending transaction the agent MUST send the owner, over the descriptor's `receiptChannel` (for example a BRC-33 message box), a message containing the `allowanceId` and the transaction as Atomic BEEF (BRC-95). The owner wallet MUST verify the transaction, internalise any new allowance outputs into the `agent allowances` basket by basket insertion, and store the BEEF. The owner wallet SHOULD show the allowance's remaining balance from the outputs it holds, and SHOULD warn the owner when receipts stop arriving while the allowance still holds funds. Once mined, each receipt's BEEF can be extended with its Merkle path. A BEEF (BRC-62) containing the funding transaction, every receipt and the sweep is a complete, self-contained record of the allowance that anyone can verify against block headers without contacting the owner, the agent or any payee. Wallets SHOULD offer it as an export. ### 3.8 Sweep To revoke, the owner wallet constructs one transaction that: * spends every allowance output it holds for the `allowanceId` through the owner branch, and * spends the revocation output, and pays the total, less fees, to the owner. The wallet MUST broadcast it immediately. Spending the revocation output revokes the agent's certificate under BRC-52 in the same transaction that recovers the funds. After the sweep, the agent's key still exists but controls no allowance outputs and carries no valid certificate. If the agent broadcasts a payment that spends an allowance output at the same moment as the sweep, whichever transaction the network accepts first wins for that output. The owner loses at most one payment per allowance output. ### 3.9 Expiry Script does not enforce `expiresAt`. The owner wallet SHOULD sweep automatically at expiry, and payees SHOULD treat a certificate whose `expiresAt` has passed as invalid. ### 3.10 Implementation with existing BRC-100 methods No new wallet methods are needed: | Step | BRC-100 methods | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Derive allowance keys | `getPublicKey` | | Fund the allowance | `createAction` with custom locking scripts and basket | | Issue the certificate | the BRC-52 certificate flow (`acquireCertificate` on the agent wallet) | | Accept the allowance, accept receipts | `internalizeAction` with basket insertion | | Agent payment or owner sweep | `createAction` with the allowance inputs, then `createSignature` with `hashToDirectlySign` over the input's signature hash, then `signAction` with the unlocking script | | Find allowance outputs | `listOutputs` on the relevant basket | Wallets that adopt the proposal natively SHOULD present allowances as their own feature (create, view, sweep) rather than leaving them to applications. ## Wallet user experience A wallet implementing allowances natively SHOULD: * show, before funding, the purpose, amount, agent identity, expiry and any permitted payees; * show every active allowance with its remaining balance; * make the sweep available as one action from the allowance and from any notification about it; * show a completed sweep with the amount returned; * offer the receipt export of section 3.7. ## Security considerations ### 6.1 Bounded loss The most an agent can spend is the value of the allowance outputs. Funding more agents does not raise any agent's limit, and an agent that funds a sub-agent can only pass on part of its own allowance. ### 6.2 Non-conforming agents An agent holding its allowance key can move the remaining balance anywhere, including to itself, instead of returning change to the allowance script. This is within the bounded loss of section 6.1: it is the worst case the owner accepted when funding. The owner loses the ability to sweep what was moved but can still revoke the certificate, because only the owner can spend the revocation output. ### 6.3 Withheld receipts An agent that withholds receipts prevents the owner from learning its current allowance outputs and so delays the sweep. It cannot exceed the cap. Owner wallets MAY look up outputs by the allowance locking script where an index is available, and SHOULD revoke the certificate when receipts are overdue. ### 6.4 Concurrent sweep and payment See section 3.8. Owners who want a smaller worst case during a sweep should split the allowance across fewer, smaller outputs, or fund smaller allowances more often. ### 6.5 Agent key compromise Compromise of the agent's key is equivalent to a misbehaving agent: loss is bounded by section 6.1 and the owner can sweep and revoke. ### 6.6 Privacy Allowance keys are derived per allowance and do not reveal the owner's identity key on-chain. Certificate fields are revealed selectively. The descriptor contains the owner's identity key and SHOULD be delivered only over an authenticated, encrypted channel. ### 6.7 Finer limits An allowance bounds the total an agent can spend, not how fast or to whom. Owners who need those limits SHOULD use an agent wallet that enforces a BRC-181 policy over the allowance outputs, and SHOULD fund smaller allowances more often rather than one large one. ## Out of scope The following are left to applications and other proposals: proxies that let agents pay providers who do not accept BSV payments; pricing and refunds for usage that is metered after the fact; reconciling a provider's invoice against receipts; and automated judgement of whether an agent stayed on task. ## Implementations None yet. A reference implementation is planned using `@bsv/sdk`, `@bsv/wallet-toolbox`, the BSV Association HTTP payment middleware and `@bsv/message-box-client`. A reference user interface for allowance creation, monitoring, sweeping and receipt checking is available on request. ## References * [BRC-29: Simple Authenticated BSV P2PKH Payment Protocol](/payments/0029.md) * [BRC-33: PeerServ Message Relay Interface](/peer-to-peer/0033.md) * [BRC-42: BSV Key Derivation Scheme (BKDS)](/key-derivation/0042.md) * [BRC-43: Security Levels, Protocol IDs, Key IDs and Counterparties](/key-derivation/0043.md) * [BRC-46: Wallet Transaction Output Tracking (Output Baskets)](/wallet/0046.md) * [BRC-52: Identity Certificates](/peer-to-peer/0052.md) * [BRC-53: Certificate Creation and Revelation](/wallet/0053.md) * [BRC-62: Background Evaluation Extended Format (BEEF) Transactions](/transactions/0062.md) * [BRC-95: Atomic BEEF Transactions](/transactions/0095.md) * [BRC-96: BEEF V2 Txid Only Extension](/transactions/0096.md) * [BRC-100: Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface](/wallet/0100.md) * [BRC-103: Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol](/peer-to-peer/0103.md) * [BRC-104: HTTP Transport for BRC-103 Mutual Authentication](/peer-to-peer/0104.md) * [BRC-105: HTTP Service Monetization Framework](/payments/0105.md) * [BRC-116: Wallet Permissions and Counterparty Trust](/wallet/0116.md) * [BRC-121: Simple 402 Payments](/payments/0121.md) * [BRC-151: BRC-100 Risk Assessment and Best Integration Practices](/opinions/0151.md) * [BRC-166: P2PKH Payments for HTTP 402](/payments/0166.md) * [BRC-172: Giving an AI Agent Control of a Delivery Vehicle Without Giving It a Wallet](/state-machines/0172.md) * [BRC-181: Wallet-Enforced Autonomous-Agent Spend Policy](/wallet/0181.md) * RFC 2119: Key words for use in RFCs to Indicate Requirement Levels * M. Fernandez, *Agent Control Protocol v1.30: Admission Control for Agent Actions*, arXiv:2603.18829 (2026) * R. Heasman, *The Payment Is the Permission* (2026) ## Appendix: example An owner funds an agent for a research task with 50,000 satoshis across four allowance outputs of 12,500 satoshis, plus a 1-satoshi revocation output, and delivers the descriptor and certificate. The agent makes 211 payments to two payees, each returning change to the allowance script, then begins retrying a failing request. Each retry is a payment and a receipt. The owner wallet notices the repeated identical payments in the receipts and the owner sweeps. One transaction spends the remaining allowance outputs and the revocation output back to the owner. One retry that was already broadcast spends its input first and settles; every other output returns to the owner. The agent's certificate is revoked by the same transaction. The owner exports a BEEF containing the funding transaction, every receipt and the sweep. A third party checks every payment against block headers without asking the agent, the payees or the owner. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://bsv.brc.dev/wallet/0204.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.