Cette page n’est pas encore traduite.

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.

instruction.md
::wallet{id=card title="Team card" account=team rails="x402/2"}
AttributeTypeMeaning
idstringRequired. What an allowance's wallet references.
accountstringThe name of the payment instrument the host holds, such as team. Never a card number, a key or a token.
railslistThe payment protocols it may be used on, each a protocol value such as x402/2.
resolverstringA resolver declared in the front matter's resolvers.
protocolstringThe 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:

instruction.md
---
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.
AttributeTypeMeaning
idstringRequired. What an extending document replaces it by, and what a host keeps its ledger by.
walletlistThe wallet or wallets it draws on: #id references to wallet objects in the document.
currencystringThe ISO 4217 code every amount is in: three uppercase letters, such as EUR.
maxstringThe most one payment may be. Above it, the agent refuses.
budgetstringThe total for each period. Required: an allowance without one limits nothing.
perstringThe period of budget and times: day, week, month, quarter, year, once. Default once, the allowance's whole life. Periods are calendar periods in UTC.
timesstringHow many payments each period, a whole number of 1 or more.
payeesstringWho may be paid: domains, merchant ids or &id references to service objects. Absent: any payee.
categorieslistKinds of purchase, such as merchant category codes or a binding's names (groceries, travel).
fromstringWhen payments may start: a date (from its start, UTC) or an RFC 3339 date-time.
untilstringWhen payments must stop: a date (through its end, UTC) or an RFC 3339 date-time.
approve-abovestringPayments above this amount, up to max, need the approver's yes each time.
approverstringWho 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, in currency. A host keeps them exactly as written: allowanceTyped in the instruction.md package 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.
  • from and until take a date or an RFC 3339 date-time. A date alone is a whole day in UTC: from=2026-12-01 starts at its first moment, until=2026-12-31 ends 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:

instruction-text/1
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:

CodeWhen
allowance-unboundedNo budget.
allowance-amount-invalidAn 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-invalidNo currency, or one that isn't three uppercase letters.
allowance-per-unknownA per that isn't one of the periods.
allowance-max-over-budgetmax above budget.
allowance-approve-above-over-maxapprove-above above max (or above budget when there is no max).
allowance-window-inverteduntil before from.
allowance-payees-invalidAn empty payees, or an entry that isn't a domain, a merchant id or an &id.
allowance-widenedA document that extends another widens an allowance it inherits.
allowance-approver-not-personAn approver that names something other than a person or a role.
reference-missingA wallet, an #approver or an &payee that names nothing in the document.
reference-kindA 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).
instruction://acme/spending-ceiling
---
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:

Narrows: lower max, budget and approve-above
---
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.
:::
Delivered
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:

Diagnostics
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:

  1. The document says it spends. An allowance adds spending to the capability families the document requires (requires in spec_validate, md.instruction/requires in an MCP resource's _meta). The sample above requires ["authority","connected","guidance","spending"].
  2. 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 capabilities claim is the version's requires. A delivery signature attests the same capabilities, never more: a verifier refuses one that names more. See Signing and verification.
  3. 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:

instruction-text/1
# 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=100Sentence
nothing moreAllowance "A" (#a): pay from #card in EUR; 100 in total.
per=weekAllowance "A" (#a): pay from #card in EUR; 100 per calendar week (UTC).
max=40 times=3 per=dayAllowance "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=20Allowance "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=#alexAllowance "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-31Allowance "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.

Last checked against the product:

Was this page helpful? Report a problem