Skip to main content

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​

StateMeaning
pending_human_approvalThe amount is above the approval threshold. The payment waits for an operator.
approvedThe payment may be signed: it was within the policy, or an operator approved it.
declinedAn operator refused it.
abandonedThe agent withdrew its own request.
consumedThe payment was signed.
expiredIts validity window ran out before it was signed.
failedA signed payment turned out not to have completed.
  1. The agent asks to pay

    • Evaluate request

      The agent gives Keyban the payment it wants to make.

  2. The policy engine evaluates

    • Spending policy

      Destination rules, caps, budgets, approval threshold.

  3. 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.

  4. Signed, then consumed

    • Approved intent

      Signed once, then consumed. If the payment never settles, it becomes failed.

The agent asks to pay. The policy engine evaluates the request. Within the policy and at or below the approval threshold, the intent is approved at once with no human. Above the threshold, the intent waits for a human, who approves or declines it. When a rule is broken, the payment is refused and no intent is created. An approved intent is signed and becomes consumed, or failed if the payment never settles.

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 approved when the amount is at or below the approval threshold, or when no threshold is set. It starts pending_human_approval when the amount is above the threshold. 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.
  • pending_human_approval to approved. 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_approval to declined. An operator declines it. An operator can decline an intent in any state except consumed. A decision can be reversed: approving an intent also revives one that was declined, abandoned or expired.
  • approved to consumed. The payment is signed. A payment goes out only from an approved intent, and it happens once.
  • approved to pending_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 reason policy/revalidation-required. Within the margin, the approval stands.
  • pending_human_approval or approved to abandoned. The agent cancels its own request with cancel_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_approval or approved to expired. 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.
  • consumed to failed. 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.