HTTP 402 + Grantex

Grantex × x402

Principal-Controlled Prepaid Wallets for Official x402 v2

Assign one or more wallets to an AI agent, reserve value before payment, enforce transaction and rolling limits, approve reloads, and stop spending at assignment, wallet, or agent level.

Try the Playground View on GitHub

npm install @grantex/x402@0.4.1 @grantex/sdk@0.8.2

Registry-verified managed prepaid-wallet APIs. External custody remains fail-closed until an operator installs and verifies a provider adapter.

The Gap in x402

x402 carries payment requirements; Grantex connects them to delegated identity, policy, and reserved prepaid value.

! Without Grantex

x402 requirements do not identify which agent may use which principal-owned funds. A reusable wallet credential alone cannot enforce recipient scope, rolling spend, reload approval, or a principal stop control.

✓ With Grantex

A DPoP-authenticated agent receives a short-lived, one-time authorization only after Grantex atomically reserves an eligible assigned wallet and enforces the principal's full policy.

How It Works

Four steps from principal policy to settled value.

Assign Wallets

The principal funds one or more wallets and assigns transaction, rolling, recipient, scope, and validity policy.

Reserve Value

After PAYMENT-REQUIRED, the DPoP agent asks Grantex to select an eligible wallet and reserve the exact amount.

Verify + Settle

The retry carries PAYMENT-SIGNATURE. The resource server verifies exact binding and settles the one-time reservation.

Reload or Stop

The agent may request a threshold reload; the principal approves and funds it or blocks one wallet or every wallet.

Developer Experience

Three APIs cover the entire flow.

Assign Policy

Agent Fetch

Emergency Stop

const wallet = await principal.create({
  name: 'Weather float',
  custodyMode: 'sandbox_ledger',
  network: 'grantex:prepaid',
  asset: 'USDC', decimals: 6
});

await principal.assign(wallet.walletId, {
  agentId, perTransactionLimit: '5000000',
  cumulativeLimit: '25000000',
  cumulativePeriodSeconds: 86400,
  allowedRecipients: ['merchant:weather-api'],
  allowedScopes: ['weather:read']
});

import { createX402Agent } from '@grantex/x402';

const x402 = createX402Agent({
  authorizePayment: walletAgent.x402Authorizer
});

// PAYMENT-REQUIRED -> reserve -> PAYMENT-SIGNATURE
const res = await x402.fetch(
  'https://api.weather.xyz/forecast'
);

// Stop one agent/wallet assignment
await principal.setAssignmentStatus(
  assignmentId, 'blocked', 'Trip ended'
);

// Or stop this agent across every principal wallet
await principal.setAgentBlocked(
  agentId, true, 'Emergency stop'
);

// Active reservations are released atomically.

One-Time Wallet Authorization

A server-signed JWT bound to a durable reservation and the exact x402 v2 requirements.

{ "reservationId": "wres_...", "walletId": "pwal_...", "assignmentId": "wasn_...", "agentId": "agt_...", "principalId": "principal_...", "amount": "1000", "asset": "USDC", "network": "grantex:prepaid", "recipient": "merchant:weather-api", "scope": "weather:read", "requestHash": "sha256:...", "exp": ... + at most 300 seconds }

reservationId

Links the signature to value already reserved in PostgreSQL.

amount + policy

Integer atomic units checked against balance, transaction cap, and rolling cap.

identity

Binds developer, principal, DPoP agent, OAuth grant, wallet, and assignment.

requestHash

Prevents changes to recipient, resource, scope, asset, network, amount, or timeout.

Features

Official x402 v2

Canonical PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE headers through the x402 Foundation packages.

DPoP Agent Identity

Wallet actions require an OAuth Agent Grants token bound to the agent's proof-of-possession key and wallet audience.

Atomic Spend Limits

Per-transaction and rolling cumulative limits count reserved and settled value while the wallet is locked.

Multiple Wallets

Pin one assigned wallet or let the service select an eligible wallet without allowing idempotent retries to drift.

Human Reload Approval

Agents request reloads only at the configured threshold; principals approve and fund in separate steps.

Immediate Stop

Block an assignment, one wallet, or every wallet for an agent and release affected outstanding reservations.

Architecture