Skip to main content

Approve payments

When an agent asks for a payment above the approval threshold of its wallet, Keyban does not sign it. It holds the payment as a payment intent and waits for a person to approve or decline it. This page shows how that person decides, and what the agent sees and does in the meantime. The threshold itself is set as described in Control spending. One exception: inside a mission a person has already validated a trial or an on_demand run, so the threshold is lifted there, and for a wallet holding a standing approval. See Missions.

  1. Agent asks

    The payment is above the approval threshold.

  2. Held

    Nothing is signed. The operators are notified.

  3. Operator decides

    Approve or decline in the Inbox.

  4. Agent retries

    An approved payment is signed once.

The agent asks for a payment above the approval threshold. Keyban holds it and notifies the operators. An operator approves or declines it in the Inbox while the agent waits. If approved, the agent retries and the payment is signed.

The diagram shows that the decision is a person's, and that the agent only retries once it has been made.

From the dashboard​

Approving or declining needs the operate right on the wallet: its operators, and Owner and Admin. It needs a person: a signed-in dashboard session or a person's own sign-in, never an API key. See Organizations, applications and wallets.

  1. Open the Inbox of the application. A held payment appears under Yours to decide with the badge Action needed when you are an operator of that wallet. If you are Owner or Admin on a wallet that has operators, it appears under You can also decide: you can decide, but the operators come first.
  2. Read the request: the agent, the amount, and the recipient for a transfer or the service for an x402 payment. The details show the wallet, the type (x402 payment or transfer), the amount, its current value in your display currency, the per-payment limit when there is one, the hash and when it was created. An x402 payment also shows a countdown to its expiry.
  3. Choose Approve or Decline.

Keyban prices the payment again at the moment you approve, so you approve its current value, not the value when it was requested. A decision can be reversed: approving an intent also revives one that was declined, abandoned or expired. A payment that is already signed can no longer be approved or declined.

The Inbox also lists the other things that wait for you, such as credit requests, treasury signatures and budget raise requests, and a Recently decided section with the last decisions. The filters at the top narrow the list by type. A budget raise request is not a payment: it asks to raise a monthly budget up to the organization, and only an organization owner can approve or decline it. See Control spending.

You are told by e-mail when a payment is held. The e-mail goes to the operators of the wallet or, when the wallet has none, to the members with the update right, and links to the Inbox.

What the agent can do​

When a payment is held, the answer of x402_pay or transfer_usdc says so and carries the intent's identifier. It is not an error: nothing is signed or sent yet. In agent apps that can show an approval card, the payment tool waits for the decision itself while the user approves from the card. The card calls two tools on its own, await_payment_approval and watch_payment_approval, which the agent never calls: they are card-only tools, which is why the tool reference does not list them. In other agent apps, the agent:

  1. Tells the user, in plain words, that a payment is waiting for them in the Inbox, and what it is for.
  2. Calls wait_for_intent in the same turn. It takes an optional timeoutMs (45 seconds, which is also the maximum), watches all the wallet's held payments at once and returns the intent that changed together with those still waiting, or the decisions of the last minutes if nothing waits any more. When it returns still waiting, the agent calls it again.
  3. When the intent is approved, calls the same payment tool again: for x402_pay, with the same URL and the intentId; for transfer_usdc, with the same recipient and amount.
  4. If the intent is declined, expired or abandoned, stops and tells the user. It starts a new request only if the user asks again.

cancel_intent withdraws the agent's own held payment and releases the budget it holds. It never approves anything. The agent cannot approve its own payment, and never starts a second payment for the same purchase while the first is held. The tools are on the Wallet MCP tools page; the refusals the agent may meet if it signs too early, such as policy/intent-pending, are on the Refusal reasons page.

Limits​

  • An approval must come from a person: the API accepts a signed-in dashboard session or a person's OAuth sign-in (the kind keyban admin login uses), and never an API key. There is no admin tool to approve, so decisions are made in the dashboard.
  • An x402 payment expires with the window the service allows, commonly a few minutes. An approval that comes too late leaves the agent to start again.
  • If the price rises above the approved value by more than the margin of the policy between approval and signature, the payment goes back to the Inbox for a new decision with the reason policy/revalidation-required.
  • An agent has one USDC transfer in flight at a time. A second one is refused with policy/intent-in-flight until the first is signed, declined or cancelled.