Allowances and wallets
This page is for developers who write instructions that let an agent pay for things, or who build a host that pays. It lists every field of wallet and allowance, the checks the reader runs on them, how an inherited allowance can only narrow, and the sentence the agent receives.
A wallet names a payment instrument the host holds. An allowance says what the agent may spend from it, on what, and who approves. Both describe limits. Neither makes a payment possible: the host pays, and only when its operator has turned spending on. See When a host applies an allowance.
Wallets
wallet is a connected object: ::wallet{…}, or a container with a body that says what it is for. It carries no card number, key or token, only the name of an instrument the host holds.
::wallet{id=card title="Team card" account=team rails="x402/2"} | Attribute | Type | Meaning |
|---|---|---|
id | string | Required. What an allowance's wallet references. |
account | string | The name of the payment instrument the host holds, such as team. Never a card number, a key or a token. |
rails | list | The payment protocols it may be used on, each a protocol value such as x402/2. |
resolver | string | A resolver declared in the front matter's resolvers. |
protocol | string | The protocol and, optionally, its versions. |
rails takes protocol values, the same as protocol on any connected object (see Protocol values). The reference library ships the x402 binding: version 2 stable, version 1 deprecated, for wallets and services. A wallet narrows what the host has: the host's own configuration says which instruments exist and on which rails, and a document picks among them.
Allowances
allowance is written only as a container, :::allowance{…} to :::. Its body says what the money is for, for the agent and for the people reading. This one allows 200 EUR a month from the team card, at most 120 a payment, to two payees, and asks the office manager before any payment above 50:
---
spec: "1"
title: Purchasing agent
parameters:
monthly: { type: string, default: "200" }
---
# Purchasing agent
Buy office supplies for the Berlin office when someone asks.
::wallet{id=card title="Team card" account=team rails="x402/2"}
::role{id=manager title="Office manager"}
::service{id=supplies-shop title="Supplies shop" src="https://supplies.example.com"}
:::allowance{id=supplies title="Office supplies" wallet=#card currency=EUR max=120 budget="${monthly}" per=month payees="&supplies-shop,stationery.example.org" approve-above=50 approver=#manager}
Paper, toner and desk supplies for the Berlin office. Nothing for personal use.
:::
MUST: pay only within :ref[the supplies allowance]{ref=#supplies}.
BECAUSE: the card is shared, and the office manager checks it every month. | Attribute | Type | Meaning |
|---|---|---|
id | string | Required. What an extending document replaces it by, and what a host keeps its ledger by. |
wallet | list | The wallet or wallets it draws on: #id references to wallet objects in the document. |
currency | string | The ISO 4217 code every amount is in: three uppercase letters, such as EUR. |
max | string | The most one payment may be. Above it, the agent refuses. |
budget | string | The total for each period. Required: an allowance without one limits nothing. |
per | string | The period of budget and times: day, week, month, quarter, year, once. Default once, the allowance's whole life. Periods are calendar periods in UTC. |
times | string | How many payments each period, a whole number of 1 or more. |
payees | string | Who may be paid: domains, merchant ids or &id references to service objects. Absent: any payee. |
categories | list | Kinds of purchase, such as merchant category codes or a binding's names (groceries, travel). |
from | string | When payments may start: a date (from its start, UTC) or an RFC 3339 date-time. |
until | string | When payments must stop: a date (through its end, UTC) or an RFC 3339 date-time. |
approve-above | string | Payments above this amount, up to max, need the approver's yes each time. |
approver | string | Who says yes: #id of a person or a role in the document, or a role's name the host binds. Never an agent. |
The table is read from the specification's registry (packages/spec/specification/registry.json) when this page is built. A rule refers to an allowance with :ref[label]{ref=#id}, which the agent reads as label (ref; #id).
The three tiers
Two numbers, approve-above and max, give three tiers within the budget, the window and the payees:
| A payment | What the agent does |
|---|---|
Up to approve-above |
Pays. |
Above approve-above, up to max |
Asks the approver, and pays only on a yes. |
Above max, over the budget, past times in the period, outside from and until, to a payee not listed, or outside categories |
Refuses. |
How the approver is asked (a chat, a passkey, a payment rail's own step-up) is the host's. Without approver, the host's own approver is asked.
Amounts, periods and windows
- Amounts (
max,budget,approve-above) are decimals of 0 or more, with at most 18 digits after the point, incurrency. A host keeps them exactly as written:allowanceTypedin theinstruction.mdpackage gives them as strings, never as floating-point numbers. - A period (
per) is a calendar period in UTC.once, the default, is the allowance's whole life. fromanduntiltake a date or an RFC 3339 date-time. A date alone is a whole day in UTC:from=2026-12-01starts at its first moment,until=2026-12-31ends after its last.- These attributes can be parameters:
max,budget,approve-above,times,from,until,currency,per. They are checked once parameters have their values. A parameter that never gets one, and has no default, is an error, never an allowance without that limit.
In the sample above, budget="${monthly}" takes its default, 200. Delivered with monthly set to 150:
Allowance "Office supplies" (#supplies): pay from #card in EUR; at most 120 per payment and 150 per calendar month (UTC); only to &supplies-shop, stationery.example.org; ask #manager before any payment above 50. Checks
The reader checks an allowance's own values when it reads the document, and again once parameters have their values and the document is composed. Every one of these is an error, so a release refuses it:
| Code | When |
|---|---|
allowance-unbounded | No budget. |
allowance-amount-invalid | An amount that isn't a decimal of 0 or more with at most 18 fractional digits; a times that isn't a whole number of 1 or more; a from or until that isn't a date or a date-time; or a parameter that never got a value. |
allowance-currency-invalid | No currency, or one that isn't three uppercase letters. |
allowance-per-unknown | A per that isn't one of the periods. |
allowance-max-over-budget | max above budget. |
allowance-approve-above-over-max | approve-above above max (or above budget when there is no max). |
allowance-window-inverted | until before from. |
allowance-payees-invalid | An empty payees, or an entry that isn't a domain, a merchant id or an &id. |
allowance-widened | A document that extends another widens an allowance it inherits. |
allowance-approver-not-person | An approver that names something other than a person or a role. |
reference-missing | A wallet, an #approver or an &payee that names nothing in the document. |
reference-kind | A wallet that names something other than a wallet. |
Each diagnostic names its allowance (target: "#id"), so a host checking one allowance finds its own. The codes are read from packages/spec/src/allowance.ts and resolve.ts when this page is built. Diagnostics and fixes lists every code of the language.
Narrowing only
An allowance can only make spending narrower than what is around it:
- It narrows the host. The effective limit is the smallest of the allowance, the host's own limits for that wallet, and what the payment rail's credential allows. A document can't create a wallet, raise a host limit, or turn spending on.
- It narrows what it inherits. An organization can publish one instruction with its ceiling and have others extend it (see Composition).
---
spec: "1"
title: Spending ceiling
---
::wallet{id=card title="Team card" account=team}
::role{id=finance title="Finance"}
:::allowance{id=supplies title="Office supplies" wallet=#card currency=EUR max=150 budget=300 per=month approve-above=100 approver=#finance}
Supplies for any office.
::: In a document that extends it, an allowance with an inherited allowance's id takes its place, and may only narrow it:
---
spec: "1"
title: Berlin purchasing
extends:
- { uri: "instruction://acme/spending-ceiling", as: org }
---
:::allowance{id=supplies title="Office supplies" wallet=#card currency=EUR max=120 budget=200 per=month approve-above=50 approver=#finance}
Supplies for the Berlin office.
::: Allowance "Office supplies" (#supplies): pay from #card in EUR; at most 120 per payment and 200 per calendar month (UTC); ask #finance before any payment above 50. Raising max instead is refused:
error: allowance-widened: #supplies: an extending document may only narrow an inherited allowance; this widens max A replace patch on an inherited allowance is checked the same way. What counts as widening, attribute by attribute:
| Attribute | Widens when the new allowance |
|---|---|
max, budget, approve-above, times |
Leaves out one the inherited allowance has, or raises it. |
per |
Changes it (once when absent). |
currency |
Changes it. |
wallet |
Names a wallet the inherited one doesn't. |
payees, categories |
Leaves out a list the inherited one has, or adds to it. |
from |
Leaves it out, or makes it earlier. |
until |
Leaves it out, or makes it later. |
approver |
Leaves out or changes an approver the inherited one names. Adding one where there was none is allowed. |
Approvers
approver is #id of a person or a role in the document (or one it inherits), or a bare role name the host binds to its own people. A #id that names anything else, such as an agent, is allowance-approver-not-person: a person or a role approves, never an agent.
When a host applies an allowance
Spending happens in a host, under three conditions:
- The document says it spends. An
allowanceaddsspendingto the capability families the document requires (requiresinspec_validate,md.instruction/requiresin an MCP resource's_meta). The sample above requires["authority","connected","guidance","spending"]. - The version is signed with that capability. A version released on instruction.md is signed with its organization's key (a self-hosted server signs only when it has a signing key), and the author signature's
capabilitiesclaim is the version'srequires. A delivery signature attests the same capabilities, never more: a verifier refuses one that names more. See Signing and verification. - The host's operator grants spending. Without that grant, a host doesn't apply the allowance, and the agent doesn't pay.
Keep an allowance's id from one version to the next. A host counts spending by allowance and period, so a new version that changes the limits applies them to what was already spent in the current period.
The delivered sentence
The agent receives an allowance under its generated heading as one fixed sentence, the same in every reader, with its amounts as they resolved, then its body. The attribute line other blocks get is not written. For the sample:
# Purchasing agent
Buy office supplies for the Berlin office when someone asks.
### wallet: Team card
Attributes: {"account":"team","rails":["x402/2"]}
### role: Office manager
### service: Supplies shop
Attributes: {"src":"https://supplies.example.com"}
### allowance: Office supplies
Allowance "Office supplies" (#supplies): pay from #card in EUR; at most 120 per payment and 200 per calendar month (UTC); only to &supplies-shop, stationery.example.org; ask #manager before any payment above 50.
Paper, toner and desk supplies for the Berlin office. Nothing for personal use.
MUST: pay only within the supplies allowance (ref; #supplies).
BECAUSE: the card is shared, and the office manager checks it every month. Each attribute adds a part, in this order:
Attributes, beside wallet=#card currency=EUR budget=100 | Sentence |
|---|---|
| nothing more | Allowance "A" (#a): pay from #card in EUR; 100 in total. |
per=week | Allowance "A" (#a): pay from #card in EUR; 100 per calendar week (UTC). |
max=40 times=3 per=day | Allowance "A" (#a): pay from #card in EUR; at most 40 per payment and 100 per calendar day (UTC); at most 3 payments per day. |
payees="shop.example.com" categories="travel" | Allowance "A" (#a): pay from #card in EUR; 100 in total; only to shop.example.com; only for travel. |
max=80 approve-above=20 | Allowance "A" (#a): pay from #card in EUR; at most 80 per payment and 100 in total; ask the host's approver before any payment above 20. |
max=80 approve-above=20 approver=#alex | Allowance "A" (#a): pay from #card in EUR; at most 80 per payment and 100 in total; ask #alex before any payment above 20. |
from=2026-12-01 until=2026-12-31 | Allowance "A" (#a): pay from #card in EUR; 100 in total; from 2026-12-01 through 2026-12-31 (UTC). |
These sentences are made by the reference resolver when this page is built (sentence in packages/spec/src/allowance.ts). What an agent receives covers the rest of the text.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
allowance-unbounded: "an allowance needs budget=… (it would limit nothing)" |
No budget. |
Add budget, and per for a period. |
allowance-currency-invalid: "currency=eur is not an uppercase ISO 4217 code" |
A lowercase or missing code. | Write it in capitals: currency=EUR. |
allowance-amount-invalid: "… has no value: its parameter is not given and has no default" |
An amount is a parameter that got no value. | Give the parameter a default in the front matter, or pass a value. |
allowance-widened: "an extending document may only narrow an inherited allowance; this widens max" |
The document raises an inherited limit. | Lower it, or change the base instruction instead. |
reference-kind: "… is a person, not a wallet" |
wallet names something that isn't a wallet. |
Point it at a ::wallet{id=…}. |
| The agent doesn't pay at all | The host hasn't granted spending, or the version wasn't signed with spending. |
Check the host's configuration. Read md.instruction/requires of the version. |
Still stuck: ask us.
Questions
Can an instruction let an agent spend money?
Only inside a host that pays and whose operator has turned spending on. The instruction's allowance then limits what the agent may spend; it can never widen what the host allows. instruction.md itself never pays. See When a host applies an allowance.
Can a team raise the organization's limit in its own instruction?
No. In a document that extends another, an allowance with the same id may only narrow the inherited one. Raising any limit is the allowance-widened error, and a release refuses it. See Narrowing only.
Can an agent approve a payment?
No. approver names a person or a role. A #id that names an agent is the allowance-approver-not-person error.
Does a new version reset what was spent?
It shouldn't. A host counts spending by allowance id and period, not by version, so a lower budget applies to what was already spent this period. Keep the id the same across versions. See When a host applies an allowance.
Related
- A purchasing agent with a spending allowance, in plain words
- Tools, skills, agents and services
- Composition:
extendsand patches - Parameters
- Signing and verification