Payment intents
Before an agent wallet pays, Keyban records what the agent wants to do. That record is a payment intent. It is what the spending policy decides on, what a person approves when a payment is held, and what the signature is later bound to. This page explains the life of an intent, so that you can tell what state a payment is in and what the agent should do about it.
Why there is an intent
A payment is never signed directly. The agent first asks Keyban to evaluate it. Keyban prices it in the wallet's reference currency, checks it against the spending policy, and answers one of three things:
- allow: an intent is created and approved at once;
- require a human: an intent is created and waits for an operator to approve it;
- deny: the payment is refused with one or more
policy/…reasons. No intent is created.
The intent holds the payment's kind, its recipient or the service it pays, the amount, the funding source and a fingerprint (a hash) of the exact request. The signature is only accepted for that fingerprint. This is what stops an agent from being approved for one payment and signing another, and from signing the same approval twice.
Asking again for the same request returns the same intent rather than a new one. On every such repeat, Keyban checks the destination rules again, so narrowing a rule takes effect even on an intent that was already approved.
The seven states
| State | Meaning |
|---|---|
pending_human_approval | The amount is above the approval threshold. The payment waits for an operator. |
approved | The payment may be signed: it was within the policy, or an operator approved it. |
declined | An operator refused it. |
abandoned | The agent withdrew its own request. |
consumed | The payment was signed. |
expired | Its validity window ran out before it was signed. |
failed | A signed payment turned out not to have completed. |
The agent asks to pay
Evaluate request
The agent gives Keyban the payment it wants to make.
The policy engine evaluates
Spending policy
Destination rules, caps, budgets, approval threshold.
no human Allowed
Within the policy
At or below the approval threshold. The intent is approved at once.
human Held for a human
Above the threshold
The intent waits for a person. An operator approves or declines it.
no intent Refused
A rule breaks
The payment is refused with policy/… reasons. No intent is created.
Signed, then consumed
Approved intent
Signed once, then consumed. If the payment never settles, it becomes failed.
In short, the policy engine either approves a payment at once, holds it for a human above the approval threshold, or refuses it with no intent, and only an approved intent is signed and consumed.
An intent that is not signed in time becomes expired, and an agent that withdraws its own request makes its intent abandoned. A human can also decline a held intent. The transitions below are all of them.
The transitions
- Created. A new intent starts
approvedwhen the amount is at or below the approval threshold, or when no threshold is set. It startspending_human_approvalwhen the amount is above the threshold. Inside a mission the threshold is lifted for a trial, for anon_demandrun and for a wallet holding a standing approval; it stays in force forautoandfrequencyruns. See Missions. pending_human_approvaltoapproved. An operator of the wallet approves it in the dashboard. The amount is priced again at that moment, so the person approves the current value, not a stale one.pending_human_approvaltodeclined. An operator declines it. An operator can decline an intent in any state exceptconsumed. A decision can be reversed: approving an intent also revives one that was declined, abandoned or expired.approvedtoconsumed. The payment is signed. A payment goes out only from an approved intent, and it happens once.approvedtopending_human_approval. The agent usually retries just before signing. If the price moved above what the person approved by more than the policy's volatility margin, Keyban sends the intent back for a fresh human decision, with the reasonpolicy/revalidation-required. Within the margin, the approval stands.pending_human_approvalorapprovedtoabandoned. The agent cancels its own request withcancel_intent. This frees the single slot described below and cannot authorize anything. A later identical request is treated as a new request. Releasing a mission run also abandons the open intents it holds.pending_human_approvalorapprovedtoexpired. The intent's validity window ends before it is signed. Keyban notices at the next evaluation, signature or listing, and then releases whatever the intent held.consumedtofailed. Keyban determines that a signed payment did not complete and can no longer complete. The amount it held is released. A signed payment cannot be withdrawn, approved or declined.
Approving or declining needs a person: a signed-in dashboard session or a person's own sign-in, never an API key. The right needed is operate on the wallet. See Organizations, applications and wallets.
How long an intent lives
- An x402 payment intent is valid for the window the seller allows for the payment, commonly a few minutes. An approval that comes too late lets the intent expire, and the agent starts again with a new request.
- A USDC transfer intent has no expiry of its own. It stays in force until it is signed, declined or cancelled.
What an intent holds against the budget
Budgets count what is already committed, not only what has settled. An intent counts against the daily, weekly and monthly budgets while it is approved or pending_human_approval and not expired, and once it is consumed. A declined, abandoned, expired or failed intent holds nothing. This is why several payments started at the same time cannot overrun a budget together.
One transfer at a time
An agent can have only one USDC transfer in flight at once, because transfers are signed with a sequential number on the blockchain. A second transfer request while an earlier one is still pending or approved is refused with policy/intent-in-flight. The agent either waits for the first or cancels it. x402 payments do not have this limit: each carries a random number, so several can run side by side.
What the agent sees
The agent does not poll intents by hand. When a payment is held, the MCP answers with the intent's identifier and tells the agent to wait. In agent apps that can show it, x402_pay and transfer_usdc wait for the decision themselves. Elsewhere, the agent calls wait_for_intent and, once the intent is approved, retries the same call with the intent's identifier. cancel_intent withdraws a request. If the agent tries to sign an intent that is not approved, Keyban refuses with policy/intent-pending, policy/intent-declined, policy/intent-abandoned, policy/intent-expired, policy/intent-failed or policy/intent-already-consumed, matching the state. Each is explained on the Refusal reasons page, and the tools are on the Wallet MCP tools page.
An agent should never start a second payment for the same purchase while the first one is held: that creates a second intent.