Agent wallets
Give an agent a spending policy in front of your own payment account.
An agent wallet puts a spending policy in front of a payment account your organization connects. The model never sees a card number. Every purchase starts as a purchase intent, and your policy decides what happens to it. You set a per-purchase cap, daily and monthly caps, a merchant allowlist, and an approval threshold. Each intent is then declined, parked for a person, or authorized. An authorized intent creates a one-time card for exactly that amount. An order the payment provider places itself may come in under the intent, never over.
Payment rails
A wallet connects to a payment account through one of two rails. You choose the rail when you create the wallet, and it stays fixed while a connection is active. One rail connects by showing a code the operator confirms in the provider's app. The other sends a code to the operator's email or phone to type back.
| Device-flow rail | Code-verification rail | |
|---|---|---|
| Connecting | Keiki shows a code, and the operator confirms it in the provider | Keiki sends a code to the operator's email or phone, and they type it back |
| Before it can spend | Nothing. The account's own payment methods are used | The account holder adds a card on a hosted page |
| A purchase | A one-time card the agent spends at checkout | A one-time card, or an order the provider places itself |
| Per-purchase limit | Up to 5,000.00 | 1.00 to 20,000.00, USD only |
| On disconnect | The grant is revoked | Open purchases are cancelled |
Connection grants are encrypted at rest and never leave the server. The provider account secret is used only to start, verify and refresh a connection.
What your agent can do
| Tool | What it does |
|---|---|
wallet_balance | What is left today and this month, the per-purchase cap, and whether a person decides |
wallet_authorize_purchase | Ask to spend on one purchase: authorized, pending_approval or declined |
wallet_purchase_status | Where an intent stands |
wallet_purchases | Recent activity |
browse with purchase_intent_id | Pay at a checkout. The card is redeemed server to server and typed in once |
wallet_buy_merchants | Where the provider can place orders itself, and whether each merchant is ready |
wallet_buy | Shop through the provider's own shopping agent and confirm a cart |
Ordering through the provider
Buying through the provider is a conversation. The agent asks in plain language, a cart
comes back with items, an all-in total and a hash. Echoing the hash as a confirm places
the order. Money moves on the confirm and nowhere else, so that is where the wallet stands.
askturns pass straight through and charge nothing.- A
confirmmust name the purchase intent. Keiki re-reads the conversation from the provider, finds the cart with that hash, and checks that its total is within the intent and its merchant matches. The agent's own account of the total never decides. - The intent is claimed once. Then the confirm is sent with the wallet's payment source: either the account holder's added card, which pauses for their approval, or the provider's default source.
- A placed order marks the intent spent. A decline, a question, or an approval pause charged nothing, so the same authorization can confirm a corrected cart. If the provider cannot say what happened, the next call asks its ledger instead of placing again.
A wallet on the device-flow rail is told that the provider does not place orders, and falls
back to paying at checkout with browse.
Wallets and purchase intents are scoped to the agent's organization.