x402 Architecture

Official x402 v2 payment messages backed by principal-controlled Grantex prepaid-wallet reservations.

Grantex uses x402 as the payment-message transport and the prepaid-wallet service as the authorization and accounting authority. Payment requirements alone do not prove that an AI agent has delegated authority or available principal-owned value; the server-issued reservation connects those facts.

Components

Component	Responsibility
Principal	Funds wallets, sets policies, approves reloads, and blocks use
OAuth authorization server	Issues DPoP-bound agent access tokens for the wallet resource
Wallet policy service	Atomically evaluates assignments, limits, allowlists, and balance
@grantex/x402 client	Converts official PAYMENT-REQUIRED into a reservation-backed PAYMENT-SIGNATURE retry
Resource server	Defines amount, asset, recipient, resource, scope, and timeout
Facilitator endpoints	Verify and settle the exact signed authorization
PostgreSQL	Serializes spend, stores reservations, and records the wallet ledger

Protocol flow

Agent              Resource server       Grantex wallet/facilitator       Principal
  | GET /resource         |                          |                         |
  |---------------------->|                          |                         |
  | 402 PAYMENT-REQUIRED  |                          |                         |
  |<----------------------|                          |                         |
  | DPoP authorize(amount, recipient, resource, scope, idempotency key)       |
  |------------------------------------------------->|                         |
  |                         lock wallet -> check policy -> reserve             |
  | signed one-time authorization                    |                         |
  |<-------------------------------------------------|                         |
  | retry PAYMENT-SIGNATURE                          |                         |
  |---------------------->| POST /v1/x402/verify     |                         |
  |                       |------------------------->|                         |
  |                       | valid                    |                         |
  |                       |<-------------------------|                         |
  |                       | POST /v1/x402/settle     |                         |
  |                       |------------------------->|                         |
  |                       | settled + transaction ID |                         |
  | 200 PAYMENT-RESPONSE  |<-------------------------|                         |
  |<----------------------|                          |                         |

Exact binding

The authorization JWT and database reservation bind:

• authorization and reservation identifiers;
• developer, principal, agent, grant, wallet, and assignment;
• amount in atomic units, asset, and network;
• recipient and exact resource URL;
• delegated action scope;
• canonical request hash and expiry.

The authorization lifetime is at most 300 seconds. The accepted x402 requirements must exactly equal the requirements supplied to the facilitator. The facilitator rejects malformed envelopes, unsupported versions/schemes, expired signatures, released reservations, and any binding mismatch. Verification is provisional. A resource server must settle successfully before starting irreversible protected work or returning the paid result; treating verification alone as payment would reintroduce a verify/use race. Remote resource URLs must use HTTPS so PAYMENT-SIGNATURE cannot disclose the one-time authorization over plaintext. HTTP is accepted only for explicit loopback development addresses.

Idempotency and replay

The agent supplies a high-entropy idempotency key when reserving. Its hash is unique across the developer, principal, and agent, not merely within one wallet. This is important for automatic wallet selection: a lost response can be retried, but the retry cannot select a different wallet or change its terms.

Settlement is idempotent and returns the original transaction identifier. Calling authorization again with a key whose reservation settled returns PAYMENT_ALREADY_SETTLED. Verification accepts only a currently reserved authorization; a settled authorization cannot verify again and therefore cannot re-run protected work. Released and expired reservations cannot be revived.

The fetch adapter accepts a caller-provided idempotencyKey. Callers should derive it from a durable logical order/request identifier and reuse it after a timeout or a lost wallet-authorization response. The generated default protects a single fetch flow, but cannot correlate two independently restarted caller invocations.

That option is deliberately not an HTTP header and cannot recover merchant work after settlement. A side-effecting merchant must also accept a normal Idempotency-Key request header, atomically persist its business result under that key, and return the cached result on a caller retry. Without that merchant record, a response lost after settlement fails closed with PAYMENT_ALREADY_SETTLED; Grantex does not replay protected work.

Blocking semantics

For grantex:prepaid, applying an assignment, wallet, or all-wallet agent block happens in the same database transaction that releases affected outstanding reservations. New authorizations fail, old authorizations stop verifying, and reserved value returns to available value. Historical settlements remain immutable.

For opt-in Base USDC, blocks prevent new signatures but cannot recall signatures already issued. These EVM reservations remain held until finalized settlement or confirmed unused expiry. Manual release, local timeout, policy mutation and RPC failure do not return that exposure to the available balance.

Legacy GDT boundary

The package still includes standalone GDT issuance and verification for signed authorization context. That path is not the managed wallet protocol. A GDT is stateless unless the host supplies durable state, so its spendLimit claim must not be described as an atomically enforced cumulative balance. New prepaid x402 integrations should use PrepaidWalletAgentClient.x402Authorizer.

External payment rails

grantex:prepaid identifies the repository’s managed prepaid settlement scheme. It does not claim an on-chain transfer. The opt-in Base USDC adapter uses standard x402 v2 exact on eip155:8453, a policy-gated EIP-3009 signer and the merchant’s EVM facilitator. Grantex checks finalized USDC funding and reconciles on-chain nonce/transfer evidence independently of the merchant’s HTTP response. It does not send an internal Grantex JWT to an EVM merchant. Other rails require separate adapters.

Base agent.fetch binds the original request URL, sends the stable logical request key as HTTP Idempotency-Key, rejects redirects and reuses the stored signature after response loss. Merchant-side result persistence is still required. Unconfigured custody, stale RPC or ambiguous evidence fails closed.