feat: add x402 upto billing policy

Author: up2itnow0822

CHANGELOG.md

@@ -1,3 +1,16 @@
+## [6.2.0] — 2026-04-13
+
+### Added
+- `UptoBillingPolicy` for x402 usage-based billing, with max authorization tracking, actual settlement recording, unused-capacity release, and wallet ledger deltas
+- Test coverage for partial settlement, finalization, over-cap rejection, and multi-settlement flows
+
+### Changed
+- Exported `UptoBillingPolicy` from the main SDK entrypoint
+- Updated README examples and package metadata to position `agentwallet-sdk` as an x402 usage-based billing reference implementation
+- Simplified `PaymentRouter.isRailLive()` boolean handling
+
+---
+
 ## [6.0.0] — 2026-03-21
 
 ### Added

README.md

@@ -1,6 +1,6 @@
 # AgentWallet SDK
 
-> **v6.0.0** · MIT · **Patent Pending**
+> **v6.2.0** · MIT · **Patent Pending**
 >
 > USPTO Provisional filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents"
 
@@ -138,6 +138,35 @@ const data = await response.json();
 // Every payment: tx hash on Base, auditable on basescan.org
 ```
 
+### Usage-based billing with x402 "upto"
+
+```typescript
+import { UptoBillingPolicy } from 'agentwallet-sdk';
+
+const upto = new UptoBillingPolicy();
+
+const auth = upto.authorize({
+  authorizationId: 'req-42',
+  service: 'api.example.com',
+  resource: 'POST /v1/generate',
+  network: 'base:8453',
+  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  payTo: '0xMerchant',
+  maxAmount: 2_000_000n, // authorize up to $2.00 USDC
+});
+
+const snapshot = upto.recordSettlement(auth.authorizationId, 740_000n, {
+  txHash: '0xsettlement',
+  finalize: true,
+});
+
+console.log(snapshot.authorization.settledAmount); // 740000n
+console.log(snapshot.authorization.releasedAmount); // 1260000n
+console.log(upto.getNetWalletDelta(auth.authorizationId)); // -740000n
+```
+
+This gives the wallet a clean local ledger for x402 usage-based billing: max authorized, actual settlement, and explicit release of unused capacity.
+
 ## The Trust Layer
 
 This is what makes supervised payments different from autonomous payments.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentwallet-sdk",
-  "version": "6.1.0",
-  "description": "Non-custodial AI agent wallet SDK. ERC-8004 identity & reputation registries, mutual stake escrow, x402 payments, 17-chain CCTP bridging, ERC-6551 TBA, SpendingPolicy guardrails, Uniswap V3 swap. The agent holds the keys.",
+  "version": "6.2.0",
+  "description": "Non-custodial AI agent wallet SDK. ERC-8004 identity & reputation registries, mutual stake escrow, x402 payments, x402 upto billing policy accounting, 17-chain CCTP bridging, ERC-6551 TBA, SpendingPolicy guardrails, Uniswap V3 swap. The agent holds the keys.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [

src/index.ts

@@ -588,6 +588,20 @@ export type {
   DraftEntry,
 } from './policy/SpendingPolicy.js';
 
+// ─── UptoBillingPolicy — x402 usage-based settlement accounting ─────────────
+export {
+  UptoBillingPolicy,
+} from './policy/UptoBillingPolicy.js';
+export type {
+  UptoAuthorizationStatus,
+  UptoAuthorizationRequest,
+  UptoSettlementOptions,
+  UptoSettlementRecord,
+  UptoAuthorizationRecord,
+  WalletLedgerDelta,
+  UptoBillingSnapshot,
+} from './policy/UptoBillingPolicy.js';
+
 // ─── Mutual Stake Escrow ─────────────────────────────────────────────────────
 export { MutualStakeEscrow } from './escrow/MutualStakeEscrow.js';
 export type {

src/policy/UptoBillingPolicy.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { UptoBillingPolicy } from './UptoBillingPolicy.js';
+
+describe('UptoBillingPolicy', () => {
+  it('tracks max authorization and exposes reservation ledger delta', () => {
+    const policy = new UptoBillingPolicy();
+    const auth = policy.authorize({
+      authorizationId: 'auth-1',
+      service: 'api.example.com',
+      resource: 'GET /inference',
+      network: 'base:8453',
+      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+      payTo: '0xabc',
+      maxAmount: 1_000_000n,
+    });
+
+    expect(auth.maxAmount).toBe(1_000_000n);
+    expect(auth.remainingAmount).toBe(1_000_000n);
+    expect(policy.getReservedAmount('auth-1')).toBe(1_000_000n);
+
+    const deltas = policy.getWalletLedgerDeltas('auth-1');
+    expect(deltas).toHaveLength(1);
+    expect(deltas[0].type).toBe('authorization');
+    expect(deltas[0].reservedDelta).toBe(1_000_000n);
+    expect(deltas[0].netWalletDelta).toBe(0n);
+  });
+
+  it('records actual settlement and wallet delta', () => {
+    const policy = new UptoBillingPolicy();
+    policy.authorize({
+      authorizationId: 'auth-2',
+      service: 'api.example.com',
+      network: 'base:8453',
+      asset: 'usdc',
+      payTo: '0xabc',
+      maxAmount: 1_000_000n,
+    });
+
+    const snapshot = policy.recordSettlement('auth-2', 420_000n, {
+      txHash: '0xsettle',
+    });
+
+    expect(snapshot.authorization.settledAmount).toBe(420_000n);
+    expect(snapshot.authorization.remainingAmount).toBe(580_000n);
+    expect(snapshot.authorization.status).toBe('partially_settled');
+    expect(policy.getNetWalletDelta('auth-2')).toBe(-420_000n);
+
+    const settlementDelta = snapshot.ledgerDeltas[1];
+    expect(settlementDelta.type).toBe('settlement');
+    expect(settlementDelta.reservedDelta).toBe(-420_000n);
+    expect(settlementDelta.settledDelta).toBe(420_000n);
+    expect(settlementDelta.netWalletDelta).toBe(-420_000n);
+  });
+
+  it('releases unused authorization capacity on finalize', () => {
+    const policy = new UptoBillingPolicy();
+    policy.authorize({
+      authorizationId: 'auth-3',
+      service: 'api.example.com',
+      network: 'base:8453',
+      asset: 'usdc',
+      payTo: '0xabc',
+      maxAmount: 1_000_000n,
+    });
+
+    policy.recordSettlement('auth-3', 250_000n, { finalize: true });
+    const auth = policy.getAuthorization('auth-3');
+    const deltas = policy.getWalletLedgerDeltas('auth-3');
+
+    expect(auth?.settledAmount).toBe(250_000n);
+    expect(auth?.releasedAmount).toBe(750_000n);
+    expect(auth?.remainingAmount).toBe(0n);
+    expect(auth?.status).toBe('settled');
+    expect(policy.getReservedAmount('auth-3')).toBe(0n);
+    expect(deltas.map((delta) => delta.type)).toEqual([
+      'authorization',
+      'settlement',
+      'release',
+    ]);
+  });
+
+  it('rejects settlement above the authorized amount', () => {
+    const policy = new UptoBillingPolicy();
+    policy.authorize({
+      authorizationId: 'auth-4',
+      service: 'api.example.com',
+      network: 'base:8453',
+      asset: 'usdc',
+      payTo: '0xabc',
+      maxAmount: 100n,
+    });
+
+    expect(() => policy.recordSettlement('auth-4', 101n)).toThrow(
+      /exceeds remaining authorized amount/i,
+    );
+  });
+
+  it('supports multiple settlements up to the authorized cap', () => {
+    const policy = new UptoBillingPolicy();
+    policy.authorize({
+      authorizationId: 'auth-5',
+      service: 'api.example.com',
+      network: 'base:8453',
+      asset: 'usdc',
+      payTo: '0xabc',
+      maxAmount: 1_000n,
+    });
+
+    policy.recordSettlement('auth-5', 250n);
+    policy.recordSettlement('auth-5', 750n);
+
+    const auth = policy.getAuthorization('auth-5');
+    expect(auth?.settledAmount).toBe(1_000n);
+    expect(auth?.remainingAmount).toBe(0n);
+    expect(auth?.status).toBe('settled');
+    expect(policy.getNetWalletDelta('auth-5')).toBe(-1_000n);
+  });
+});