Skip to main content

Control spending

Each agent wallet has a spending policy that Keyban enforces on its servers before it co-signs a payment: a cap per payment, budgets per day, week and month, an approval threshold, rules on where the wallet may pay, and an emergency stop. Above the wallet, monthly budgets cap what a whole application and the whole organization spend. This page shows how to set each of them and what the agent sees. The order in which Keyban checks a payment is explained in Spending policy.

From the dashboard​

Set the caps, the budgets and the approval threshold​

Open Agent Wallets, then the wallet, and choose Edit on the Spending rules card, which opens the Edit policies dialog. It needs the update right on agent wallets (Owner and Admin). Amounts are written in the display currency of your organization.

Field in the dashboardWhat it does
Maximum amount per transaction (shown as Refuse above on the card)A payment above it is refused.
Human approval above (shown as Ask me above on the card)A payment above it is held in the Inbox until a person approves it. See Approve payments.
Daily budget (capped) (Daily cap on the card)What the wallet may spend over the calendar day. Beyond it, payments are refused until tomorrow.
Weekly budget (capped) (Weekly cap on the card)The same over the week, Monday to Sunday. Refused until Monday.
Monthly budget (capped) (Monthly cap on the card)The same over the month. Refused until the 1st.

An empty field means no limit. The dashboard checks that the weekly budget is not lower than the daily one, and the monthly budget not lower than the weekly one. A budget counts what the wallet already spent plus what its open intents hold, so payments started at the same time cannot overrun it together. The time zone of the windows and the price tolerance between approval and signature (timezone and volatilityMarginBps) are fields of the policy that the dashboard form does not show; they are set through the API or the admin tools (keyban admin commands, or the Keyban MCP server after keyban admin login).

Choose where the wallet may pay​

Destination rules are allow-lists or deny-lists, with addresses for USDC transfers and domains for x402 payments. They exist at three levels, and a payment must pass every level:

LevelWhere to edit itRight needed
WalletDestination rules card on the wallet pageupdate on agent wallets
ApplicationSettings, then Security, then Application destinationsupdate on agent wallets
OrganizationOrganization settings, then Organisation destinationsThe organization settings right (Owner and Admin)

A level with no rule does not restrict anything. The organization rule is the outermost guard-rail: the levels below can only narrow it. On the Services page, an administrator can also authorize an x402 service in one click, which edits the organization rule.

Set the monthly budgets​

A monthly budget caps what all the agent wallets of an application, or of the whole organization, spend together in a calendar month. The concept (levels, free share, strict allocation, one currency) is explained in Spending policy. The organization display currency must be chosen first: a budget is written in it. The dashboard labels these budgets "envelope", for example the card Monthly envelope, and this page keeps those labels in bold.

LevelWhere to set itWho can
OrganizationGlobal Budget in the menu, card Monthly envelopeOrganization owners only
ApplicationBudget in the menu of the application, card Monthly envelopeOwner and Admin (the update right on agent wallets)
WalletThe Monthly budget (capped) field of the Edit policies dialog, opened with Edit on the Spending rules card of the walletOwner and Admin (the update right on agent wallets)

Members who cannot edit see these pages in read-only mode. The same pages also hold the Destinations cards described above, and a chart of how the budget is shared among its children: for each child, its budget and what it spent this month, then the free share. A child that holds more than its parent can give is marked Above the envelope, and Bring back to the envelope sets it to what its parent can give.

  1. Open the page and choose Set a limit (or Edit when one exists). Enter the Monthly limit. On the organization card, also choose the Time zone: the month starts at midnight in it, for every level. UTC is the default.
  2. Choose Save.

What happens on Save:

  • It fits in what the parent can give. It is saved. The parent is the organization for an application, and the application for a wallet. What it can give is its budget minus the budgets of its other children. A wallet or application with no budget above it is not limited by it.
  • It does not fit, but the chain of raises stays below the organization. Nothing is saved yet. The dashboard shows a preview of the raises, for example the application going from 600 to 650, and asks you to confirm them. On Confirm the raises, the whole chain is applied at once.
  • It would need the budget of the organization to rise. Only an owner can decide that. If you are an owner, the preview shows the chain, including the organization, and you confirm it. If you are not, the dialog says "This setting exceeds the organization envelope. The owner has to raise it from … to …. Send the request?": Send the request creates a raise request for the owners, and nothing is changed until one of them approves. The previous budget stays in force meanwhile.
  • A new wallet does not fit. Creating a wallet whose monthly budget does not fit in the free share of an application that has a budget is refused with the 409 preview and has no confirm step: raise the budget of the application first.
  • You lower a budget, or remove it. After a confirmation that states the consequence, it applies at once. If children no longer fit, the dialog counts them: they stay marked Above the envelope and none of their settings changes. Removing the budget of an application makes its wallets spend from the free share of the organization, with no guaranteed share.

The preview is the same in the API: the first call answers 409 ENVELOPE_CHAIN_CONFIRMATION_REQUIRED with the chain and a digest and writes nothing, and the same call repeated with confirmChain: true and that chainDigest applies it. If a budget changed between the preview and the confirmation, nothing is applied and a fresh preview is returned.

Decide a raise request​

A raise request arrives in the Inbox of the application the request is about (the application, or the application of the wallet), as a Budget raise requested item that shows who asks, for which wallet or application, and the raises it takes. All owners of the organization also get an e-mail with a link to it. Only an organization owner can Approve or Decline it: an administrator, even for their own request, cannot, and neither can an API key. Other members who can read agent wallets see it read-only, and the person who asked can Cancel my request. See Approve payments for the rest of the Inbox.

  • On Approve, Keyban recomputes the chain on the current state and applies it as one block: the budget asked for and the raises above it. If the chain differs from the one the owner saw, for example because another request was approved meanwhile, nothing is applied, the owner is shown the updated chain and confirms again.
  • On Decline, nothing changes.
  • The person who asked is told of the decision by e-mail. A different request on the same wallet or application replaces the pending one, which becomes cancelled; an identical one from the same person changes nothing and sends no new e-mail.

Budget alerts​

Keyban sends an e-mail alert for each budget, and for each free share, in two cases:

  • Off pace. From the third day of the month (in the time zone of the organization), when the spend so far, continued at the same rate, would use up the budget before the month ends. The e-mail gives the date it would run out. A part that has spent less than a quarter of its cap sends nothing. During the first two days the rate is not reliable, so the e-mail is sent when the spend reaches 80 percent of the budget instead.
  • Used up. When the month's spend reaches the budget.

Each alert is sent once per month for each budget or free share, even if the spend dips and rises again. Raising a budget so that the alert is no longer due arms it again. Recipients are the owners for the organization budget, the owners and admins for an application budget, and also the operators of the wallet for a wallet budget. When a budget is lowered below what its children hold, owners and admins also get an e-mail listing what is now above it.

The same states show as a banner at the top of the Budget page: orange when the pace would use the budget up before the end of the month, red when it is used up, with the button Request a raise or Adjust the envelope according to your rights. An alert asks for no decision, so it does not appear in the Inbox. Alerts are checked after each payment, so a month with no payment sends none. Keyban e-mails people when a monthly budget (the organization's, an application's, a free share, or the monthly budget of a wallet whose application has a budget) is on pace to run out and when it is used up; other alerts to a human, such as velocity alerts or alerts when a wallet with no budget above it reaches its limits, are Coming soon.

Pause a wallet: the emergency stop​

The Pause button in the header of the wallet page stops the wallet at once, after a confirmation. While it is paused, every payment request from that wallet is refused with policy/emergency-stop, including a payment that was approved but not yet signed. Resume lifts it. Anyone with the operate right on the wallet can use it: its operators, and Owner and Admin. It is a flag in the policy enforced by Keyban's servers, not a rule on the blockchain.

What the agent can do​

The agent cannot change its own limits or lift a pause: its key can ask Keyban to evaluate payments and nothing else. What it sees is the effect of the limits:

  • A payment within the limits goes through.
  • A payment above the approval threshold is held. The agent tells the user to approve it and waits with wait_for_intent.
  • A payment that breaks a cap, a budget or a destination rule is refused with one or more policy/… reasons, all returned together. A refusal on a monthly budget names the level: policy/budget-application-month-exceeded or policy/budget-organization-month-exceeded when a budget is used up, and policy/budget-application-free-share-exceeded or policy/budget-organization-free-share-exceeded when the free share of a parent is used up. The agent reports them to the user, tells which budget to raise, and drops that payment.
  • On a paused wallet, every payment is refused with policy/emergency-stop.

The agent should never split a payment to stay under a cap or an approval threshold, and never route a payment around a destination rule. Each reason and what to tell the user is on the Refusal reasons page.

An assistant using the admin tools of the Keyban MCP server, after keyban admin login, works with the rights of the person who signed in and can do what the dashboard does: get_wallet_policy, set_wallet_policy, reset_wallet_policy, freeze_wallet and unfreeze_wallet. For the organization and application budgets, which the API and the admin tools call a shared budget, it has get_application_shared_budget, set_application_shared_budget, delete_application_shared_budget and the three organization equivalents (set_organization_shared_budget and delete_organization_shared_budget work for an owner only). set_wallet_policy and set_application_shared_budget work in the same two steps: when the value does not fit, the first call writes nothing and returns the preview of the chain, the assistant shows it to the user, and repeats the call with confirmChain and the chainDigest only once the user agrees. When the chain reaches the organization and the user is not an owner, the confirmed call returns 202 with the raise request and writes nothing, including the other fields of the policy: repeat it once an owner approved. Approving or declining a raise request is not an MCP tool: the owner does it in the Inbox. See the Admin tools.

Limits​

  • The smallest limit you can set is one cent of the display currency.
  • Limits are written in the display currency, which is chosen once for the organization and cannot be changed afterwards. A payment in USDC is converted at the current rate before it is compared.
  • Editing a policy and its destination rules needs update; pausing needs operate. They are separate on purpose. See Organizations, applications and wallets.
  • A key bound to one agent wallet cannot set the budget of an application or of the organization, or raise its own budget: it is refused with 403.
  • A monthly budget cannot be set in the day or week windows: only the month exists at the organization and application levels. A body that sends a daily or weekly cap there is refused with 400, and so is a time zone sent for an application: the time zone belongs to the organization.
  • Under a budget, a wallet policy must be in the display currency of the organization (ENVELOPE_CURRENCY_MISMATCH, 422).
  • Velocity limits Coming soon are not available yet.
  • Alerts to a human other than the budget alerts Coming soon are not available yet: see Budget alerts.