Skip to main content

Spending policy

Keyban enforces a spending policy before it co-signs a payment. The policy runs on Keyban's servers, not inside the agent, so the agent cannot skip it or edit it. It is how you control what an agent wallet may do: where it may pay, how much, when a person must approve, and how to stop it at once. The diagram shows the controls side by side.

  1. Where it may pay

    • Organization rules

      Allow-list or deny-list

    • Application rules

      Narrow the organization's

    • Wallet rules

      Narrow the application's

    • Mission sources

      Only these services during a run

    How much

    • Organization budget

      Per month

    • Application budget

      Per month

    • Wallet budgets

      Per day, week, month

    • Per-payment cap

      Per payment

    • Mission envelope

      Per run

    When a person decides

    • At or below the threshold

      The agent pays alone

    • Above the threshold

      An operator approves

    • Emergency stop

      A person pauses the wallet: every payment is refused

  2. Paid

    • Co-signed by Keyban

      Only a payment that passes every control

Three kinds of control apply side by side. Where the agent may pay: the destination rules of the organization, the application and the wallet, and the sources of a mission during a run. How much it may spend: the organization and application monthly budgets, the wallet's day, week and month budgets, the per-payment cap and the run envelope of a mission. When a person decides: at or below the approval threshold the agent pays on its own, above it the payment waits for an operator, and a person can pause the wallet with the emergency stop, after which every payment is refused. Keyban co-signs only a payment that passes every control.

In short, you control where an agent wallet may pay, how much it may spend over a payment, a run, a day, a week and a month, when a person must approve, and you can stop it at once; Keyban co-signs only what passes all of it. A few technical checks also run, such as whether the service can be paid at all: they are listed in How a payment is checked.

What a policy is​

A policy exists at three levels: the organization, the application and the wallet. At every level it is made of the same two things:

  • Destination rules: where the payments may go.
  • A monthly budget: how much may be spent in a month.

The wallet level adds controls of its own, described in Controls of the wallet: a per-payment cap, daily and weekly budgets, the approval threshold, a price margin, a time zone, a mission requirement and the emergency stop.

LevelDestination rulesMonthly budgetControls of its own
OrganizationYesYesNo
ApplicationYesYesNo
WalletYesYesYes

The levels go from the widest to the narrowest. A lower level can only narrow what a higher level allows. The rest of this page follows that order: destination rules, then budgets, then the controls of the wallet.

Destination rules​

A destination rule says where the payments of a level may go. It guards against an agent that pays a service or an address you never meant it to. The organization rule is the outermost guard-rail, the application rule narrows it for the wallets of one application, and the wallet rule narrows it again for one wallet.

A rule is an allow-list (only these destinations) or a deny-list (anything but these). Each level has one rule, and a rule has one mode: a level is either an allow-list or a deny-list, never both. Different levels can use different modes: an allow-list at the organization and a deny-list at the wallet both apply.

Each rule holds two separate lists, one for each way an agent pays. Both lists share the mode of the rule:

  • addresses, for USDC transfers, matched exactly and compared in lowercase;
  • domains, for x402 payments, written as a bare domain such as example.com. A domain also covers its sub-domains: openai.com matches api.openai.com.

A list that is not set does not restrict that kind of payment at that level. For an allow-list, an empty list means nothing is allowed. For a deny-list, an empty list denies nothing.

The levels combine by intersection, and the strictest wins. A destination must pass the rule at every level that has one. A lower level never widens a higher one: a wallet cannot allow a domain that the organization denies. A refusal names the level that stopped it, for example policy/domain-organization-denylisted or policy/recipient-wallet-not-allowed.

LevelApplies toEdited with
OrganizationEvery wallet of the organization.The organization settings right: Owner and Admin.
ApplicationEvery wallet of the application.The update right on agent wallets: Owner and Admin.
WalletOne wallet.The update right on agent wallets: Owner and Admin.

Where to edit each level in the dashboard is in Control spending.

Monthly budgets​

A monthly budget caps what a group of wallets spends together over a calendar month. It exists at two levels above the wallet: the organization, where it is the hard cap for every wallet, and each application. The wallet has budgets of its own, described in Controls of the wallet. A budget does not name destinations, and it is not a limit written for each wallet. The dashboard and the API give these budgets other names, listed in Control spending.

How these budgets behave:

  • Calendar month, in the time zone of the organization. Only the month exists at the organization and application levels: there is no daily or weekly budget there. The month starts at midnight in the time zone set once on the organization budget (UTC by default), and that time zone serves every level.
  • One currency. A budget is written in the display currency of the organization, which is chosen once and cannot change. Under a budget, every wallet policy must be in that currency. A wallet policy in another currency is refused with ENVELOPE_CURRENCY_MISMATCH, and so is a budget over wallets whose policy is in another currency. A payment that meets such a mismatch is refused with policy/budget-currency-mismatch.
  • Strict allocation. What the budgets of the children add up to never exceeds the budget of their parent: the applications inside the organization, and the wallets inside an application. No write can allocate more than the parent holds, and there is no override; lowering a parent is the only way to end up above it.
  • Free share. A parent keeps what is left once the budgets of its children are set aside: its free share. A child with no budget of its own spends from the free share of its parent. The children with no budget share it, first come first served, and none of them can touch what is reserved for a sibling that has a budget. A child with a budget never spends more than its budget.
  • A guarantee only exists along a chain of budgets. Under an application that has no budget, the monthly budget of a wallet is a plain cap: it takes no part in the allocation of the organization and nothing guarantees it. The application spends from the free share of the organization, like any application with no budget.
  • No budget above, no restriction. A level with no budget imposes nothing on the levels below it.
  • Lowering never cascades. An Owner (for the organization budget) or an Owner or Admin (for an application) can lower a budget below what its children hold. The change applies at once and no setting of the children is touched. The dashboard marks the children that are now Above the envelope, and the parent stays the hard ceiling: when the budgets handed out exceed it, the children with no budget are refused, and the children with a budget spend within theirs but never together beyond the parent.

A payment that would overrun a budget is refused outright, with no human approval, and the reason names the level: policy/budget-application-month-exceeded or policy/budget-organization-month-exceeded when the budget is used up, policy/budget-application-free-share-exceeded or policy/budget-organization-free-share-exceeded when the free share is used up. Spending counts what the wallets of the level already spent in the month plus what their open intents hold. The wallet's own budgets keep applying on top.

Who sets which budget, and how a raise is requested and approved, is in Control spending.

Controls of the wallet​

These controls exist only on the wallet. The policy of a wallet is created together with the wallet and has these fields:

FieldWhat it does
currencyThe reference currency the amounts below are written in. The dashboard offers euro, US dollar and yen. A payment made in USDC is converted to this currency at the current rate before it is compared.
maxAmountPerPaymentRefA ceiling for one payment. Empty means no cap.
maxAmountPerDayRef, maxAmountPerWeekRef, maxAmountPerMonthRefThe wallet's own budgets over the current calendar day, week (Monday to Sunday) and month. Empty means no budget for that period. The monthly one is the wallet's budget at the third level, described above.
requireHumanAboveRefThe approval threshold, described below. Empty means a human is never required.
volatilityMarginBpsHow much the price may rise, in basis points (100 is 1 percent), between the moment a person approves a payment and the moment it is signed. Beyond it, the payment goes back for a new approval. Empty or zero means no tolerance.
timezoneThe time zone in which the day, week and month windows are computed, as an IANA name such as Europe/Paris. Empty means UTC. When a monthly budget sits above the wallet, the month is counted in the time zone of the organization instead.
missionRequiredWhen true, the wallet can pay only inside an approved mission run, through the x402_pay_in_mission and transfer_usdc_in_mission tools. A payment that names no run is refused with policy/mission-required.
emergencyStopWhen true, every payment request from the wallet is refused. It is changed with its own action, described below.

An amount is a whole number in the smallest unit of the reference currency: 3000 is 30.00 euros. Keyban does not support limits below one cent of the reference currency, so one cent is the finest limit you can set.

The approval threshold​

The approval threshold, requireHumanAboveRef, decides when a human has to step in. It is set by the person responsible for the wallet.

  • At or below the threshold, the agent pays on its own. A payment that passes every other check and whose amount is at or below the threshold is approved at once and signed with no human action.
  • Strictly above the threshold, the payment is held. Its intent waits in pending_human_approval until an operator approves or declines it. An amount exactly equal to the threshold is not above it, so it passes.
  • No threshold, no human. An empty threshold means a human is never asked.
  • The amount is rounded up to the cent. Keyban compares the amount in the reference currency, rounded up to the next cent.
  • A price that drifts after an approval can bring a human back. If the price rises by more than the volatility margin between the approval and the signature, the payment goes back for a new approval, with the reason policy/revalidation-required.
  • Inside a mission, the threshold is lifted for a trial, for an on_demand run and for a wallet holding a standing approval. It stays in force for auto and frequency runs. See Missions.

The threshold only decides about payments that are otherwise allowed. A payment that breaks a rule is refused with no human approval. What happens to a held payment is in Payment intents, and how to approve it is in Approve payments.

How a payment is checked​

When the agent asks to pay, Keyban evaluates the request. These checks run, in this order:

  1. The monthly transaction quota of the organization, which comes with the plan. When it is used up and blocking is on (the default), every wallet of the organization is refused with policy/transaction-quota-reached; with blocking off, payments go on and the extra transactions are billed (see Plans and quotas).
  2. The mission checks, when the payment names a mission run or the wallet requires one: the run must exist and be active. Otherwise the payment is refused with policy/mission-run-not-found, policy/mission-run-not-active or policy/mission-required.
  3. The wallet has an address. A wallet whose smart account is not deployed yet is refused with policy/wallet-not-deployed.
  4. The destination rules of the three levels, together. For an x402 payment this check runs before Keyban contacts the seller at all, so a service you refused is never called. Every rule that blocks is reported.
  5. The emergency stop. A paused wallet is refused with policy/emergency-stop.
  6. The service can be paid. For an x402 payment, Keyban reads the service's payment options with one request. The service must offer the exact scheme, on the wallet's own network, in USDC, and its price must not exceed the maximum the agent set for the call. Otherwise the payment is refused with a policy/x402-… reason.
  7. Who pays. When the Keyban welcome offer would pay and the organization has not accepted Keyban's terms, the payment is refused with policy/terms-not-accepted.
  8. The caps and the budgets, all evaluated together: the destination rules again, the monthly budgets of the organization and of the application with their free share, the day, week and month budgets of the wallet, the per-payment cap, and the run envelope of a mission. The budgets count what was already spent plus what the open intents hold. See Payment intents. Every reason is returned together: a payment that breaks an allow-list and a cap is refused with both reasons, so the agent and the user see everything at once.
  9. The approval threshold. A payment that passed everything above is allowed at once, or held for a human if it is above the threshold.

A check from 1 to 7 stops at the first failure. Step 8 collects every reason, and step 9 runs only when step 8 found none. A USDC transfer has no service to read and no funding choice, so it skips steps 3, 4, 6 and 7: its destination rules are checked in step 8, with the caps and budgets, right after the emergency stop of step 5.

Keyban does not check the balance of a wallet that holds its own USDC before it approves a payment. A payment above the balance is approved by the policy and fails when it settles.

A refusal carries reasons that start with policy/. They are listed with what to say to the user on the Refusal reasons page. The agent should report the reason and drop that payment. It should never split a payment to stay under a cap or an approval threshold, and never route a payment around a destination rule.

Velocity limits Coming soon are not shipped yet. 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. The alerts themselves are described in Control spending.

The emergency stop​

The emergency stop pauses one wallet at once. A person with the operate right on the wallet can pause it and resume it, from the dashboard or with the admin tools of the Keyban MCP server, after keyban admin login (see CLI, MCP and API). While it is paused, every payment request from that wallet is refused with policy/emergency-stop, until someone resumes it. The dashboard shows Paused in place of the wallet's status.

It is a flag in the policy, enforced by Keyban's servers. It is not a rule written on the blockchain. It also applies to a payment that was already approved but not yet signed: Keyban checks it again at signing time.

The end of the free trial uses the same flag: it pauses every wallet of the organization, and an upgrade resumes only the wallets that the trial end paused. A wallet that a person paused stays paused.

Who changes what​

The person who decides the limits is not the person who runs the agent, and neither is the agent:

  • The destination rules of the organization need the organization settings right: Owner and Admin. Those of an application or a wallet need the update right: Owner and Admin.
  • The monthly budget of an application, and the policy of a wallet, need the update right: Owner and Admin. The monthly budget of the organization is set by an Owner only, and so is the decision on a raise that reaches it.
  • Pausing the wallet, and approving or declining held payments, needs the operate right: operators of the wallet, and Owner and Admin.
  • The agent's own key can only ask Keyban to evaluate payments. It cannot edit the policy or approve a payment.

See Organizations, applications and wallets.