Agent Prepaid Wallets

Principal-controlled prepaid balances, multi-wallet assignment, spend policy, reload approval, and emergency blocking for AI agents.

Agent prepaid wallets give a human principal a durable value and policy boundary for autonomous spending. A wallet can be assigned to multiple agents, and an agent can hold multiple wallet assignments. Assignment safeguards combine with layered wallet, agent, budget-group, principal, and developer policy.

Lifecycle

1. A developer registers an agent for the wallet:read, wallet:spend, the merchant action scope (for example travel:book), and optional wallet:reload:request scopes.
2. The principal authorizes those scopes through OAuth Agent Grants.
3. The application creates a short-lived principal session.
4. The principal creates and funds one or more wallets.
5. The principal assigns wallets with transaction, rolling, recipient, resource, scope, validity, and optional shared budget-group policy.
6. The DPoP-authenticated agent reserves value before presenting a payment.
7. A layered policy may deny, allow, or require an exact principal approval.
8. The resource server verifies and settles the one-time authorization.
9. The principal reviews decisions, approves payments or reloads, or blocks spending.

Wallet states

State	New authorizations	Existing reservations	Reload
active	Allowed by assignment policy	Verifiable and settleable	Allowed by workflow
blocked	Denied	Released when the block is applied	Denied to the agent
closed	Denied permanently	Released when the close is applied	Denied

Assignments independently use active, blocked, or revoked. Revocation is terminal. A principal can also set allWalletsBlocked for one agent, scoped to that principal and developer.

Balance accounting

Balances are NUMERIC(78,0) atomic-unit integers:

funding:       available += amount
reservation:  available -= amount; reserved += amount
settlement:   reserved  -= amount
release:      reserved  -= amount; available += amount

Every transition and the resulting balance is recorded in the wallet ledger. The application role receives no update or delete permission on ledger rows. The database checks that available and reserved values never become negative.

Assignment and layered policy evaluation

An authorization succeeds only if all of these remain true while the wallet row is locked:

• wallet, assignment, grant, and OAuth access token are active;
• the agent is not globally blocked by the principal;
• assignment validity dates include the current time;
• asset and network match the wallet;
• recipient, HTTPS resource origin, and scope are explicitly allowed or the corresponding allow-any choice was made;
• the payment scope is present in the human-approved OAuth grant;
• amount does not exceed the per-transaction cap;
• reserved plus settled value in the rolling window, plus the new amount, does not exceed the cumulative cap;
• enough available value exists.

After the assignment checks, every matching policy is evaluated. Policies can scope to an assignment, wallet, agent, shared budgetGroup, principal, or developer. They can deny, always require approval, or enforce amount and count limits over per-authorization, rolling, day, week, month, or lifetime windows. Filters cover recipient, resource origin, action scope, asset, network, merchant ID, purpose, project ID, cost center, and verified merchant state.

All matching layers compose; a narrow policy cannot override a broader deny or increase a stricter limit. Reserved and settled amounts both count toward usage. Cross-wallet and cross-agent policy evaluation uses a shared advisory lock, while balance movement uses the wallet row lock.

Concurrent requests serialize on the wallet row. The database update also requires available_amount >= amount, so a race cannot overdraw the wallet even if callers arrive together.

Exact payment approval

A policy can return approval_required instead of creating a reservation. The approval is durable, short-lived, and bound to the exact agent, wallet, assignment, amount, asset, network, recipient, resource, scope, merchant, purpose, project, cost center, matched policies, and idempotency key. The principal approves or rejects it through the dashboard or principal-session API.

An approved retry must repeat the original terms and is consumed when the reservation succeeds. It cannot be reused for a different transaction. The authorization JWT also binds the semantic context, so changing it at x402 verification or settlement fails closed.

Reload separation of duties

An agent may ask for a reload only when available value reaches the configured low-balance threshold. It cannot approve or fund the request. The principal can:

• approve, then fund;
• reject;
• leave the request pending;
• fund directly without an agent request in sandbox mode.

Wallet-level reload controls can cap maximum balance, a single reload, cumulative reload amount and period, and reload count and period. The server rechecks these limits when funding, after the principal decision, so an old approval cannot bypass newer balance or velocity state.

Only one pending request per agent and wallet exists. The agent persists an idempotency key before the first call and reuses it for the exact request. That replay returns the same record through pending, approval/rejection, and funding; changed terms or a second key while another request is pending conflict.

Approval/rejection and funding are response-loss safe: repeating the same decision or funding call returns the existing result without crediting twice. A contradictory decision or external funding reference returns a conflict.

Agent wallet listings expose policy and balances, but not custody-provider identifiers, wallet addresses, principal identifiers, or wallet metadata.

Custody boundary

sandbox_ledger is the internal-ledger implementation. It is suitable for local development, deterministic integration tests, and off-chain prepaid accounting where the Grantex ledger is explicitly the system of record.

external with operator-configured base_usdc supports native Base USDC EIP-3009 payments. It verifies finalized funding receipts and settlement evidence and persists signatures with balance reservations. See Base USDC custody for provisioning, SDK availability and the in-process signing-key risk. Other or unconfigured providers fail with CUSTODY_ADAPTER_UNAVAILABLE. Arbitrary provider references never become spendable value.

For Base, blocking prevents new signatures but does not cancel already signed payments. Those reservations remain held and count against limits until finalized settlement or unused expiry, including across server restarts and RPC outages. Reconciliation never accepts caller-invented settlement evidence.

API families

Principal-session endpoints are under /v1/principal/prepaid-wallets* and cover wallets, assignments, direct reloads, reload decisions, activity, and release or block actions. Principal policies and exact approvals use /v1/principal/prepaid-wallet-spend-policies* and /v1/principal/prepaid-wallet-payment-approvals*. Developer-level policies use /v1/prepaid-wallet-spend-policies* under API-key authentication. DPoP agent endpoints are under /v1/prepaid-wallets* and cover listing, payment authorization, and reload requests. The official x402 v2 facilitator endpoints are /v1/x402/supported, /v1/x402/verify, and /v1/x402/settle.

See the x402 integration guide for code and failure handling and Agent Wallet Governance for the Grantex, issuer, runtime, principal, and merchant boundaries. Self-hosting operators must also complete Prepaid Wallet Production Readiness for public routing, migration, notification, merchant-recovery, custody, and external-review dependencies.