@agentokratia/x402-escrow 2.0.1 → 2.1.1

package/README.md

@@ -1,13 +1,13 @@
 # @agentokratia/x402-escrow
 
-Escrow payment scheme for the x402 protocol. Session-based payments for high-frequency APIs.
+Escrow payment scheme for the x402 protocol. Supports direct USDC payments and cross-token swaps.
 
 ## Features
 
-- **Session-based payments** - Sign once, make unlimited API calls
-- **Zero per-request gas** - Facilitator handles on-chain transactions
-- **100% reclaimable** - Withdraw unused funds anytime
-- **ERC-3009 gasless** - Users sign off-chain, no wallet transaction needed
+- **Direct USDC payments** - Gasless via ERC-3009 ReceiveWithAuthorization
+- **Multi-token support** - Pay with WETH, DAI, USDT → receiver gets USDC
+- **Automatic swap quotes** - Server fetches DEX quotes, client just signs
+- **Gzip compression** - Aggregator calldata compressed for smaller payloads
 
 ## Installation
 
@@ -19,140 +19,260 @@ npm install @agentokratia/x402-escrow
 
 For apps and agents paying for APIs.
 
-### Simple (recommended)
+### Basic Setup
 
 ```typescript
-import { createEscrowFetch } from '@agentokratia/x402-escrow/client';
-
-const { fetch: escrowFetch, scheme, x402 } = createEscrowFetch(walletClient);
-
-// Payments handled automatically
-const response = await escrowFetch('https://api.example.com/premium');
-
-// Access sessions
-scheme.sessions.getAll();
-scheme.sessions.hasValid(receiverAddress, '10000');
-```
-
-### With hooks
-
-```typescript
-const { fetch: escrowFetch, x402 } = createEscrowFetch(walletClient);
-
-// Add hooks for user control
-x402.onBeforePaymentCreation(async (ctx) => {
-  console.log('About to pay:', ctx.paymentRequirements);
-});
+import { EscrowScheme } from '@agentokratia/x402-escrow/client';
+import { x402Client } from '@x402/core/client';
+import { ExactEvmScheme } from '@x402/evm';
+import type { WalletClient } from 'viem';
+
+// Convert wagmi WalletClient to x402 signer
+function walletClientToSigner(walletClient: WalletClient) {
+  return {
+    address: walletClient.account!.address,
+    signTypedData: async (message) =>
+      walletClient.signTypedData({
+        account: walletClient.account!,
+        domain: message.domain,
+        types: message.types,
+        primaryType: message.primaryType,
+        message: message.message,
+      }),
+  };
+}
+
+// Create x402 client
+const client = new x402Client();
+
+// Register exact scheme for direct USDC payments
+const exactScheme = new ExactEvmScheme(walletClientToSigner(walletClient));
+client.register('eip155:8453', exactScheme);
+
+// Register escrow scheme for swap payments
+const escrowScheme = new EscrowScheme(walletClient);
+client.register('eip155:8453', escrowScheme);
 
-x402.onAfterPaymentCreation(async (ctx) => {
-  console.log('Payment created:', ctx.paymentPayload);
-});
+// Create payment payload from 402 response
+const paymentPayload = await client.createPaymentPayload(paymentRequired);
 ```
 
-### Advanced (manual setup)
+### With Policies (Token Selection)
 
 ```typescript
 import { x402Client } from '@x402/core/client';
-import { wrapFetchWithPayment } from '@x402/fetch';
-import { EscrowScheme, withSessionExtraction } from '@agentokratia/x402-escrow/client';
-
-const escrowScheme = new EscrowScheme(walletClient);
-const x402 = new x402Client().register('eip155:84532', escrowScheme);
-const paidFetch = wrapFetchWithPayment(fetch, x402);
-const escrowFetch = withSessionExtraction(paidFetch, escrowScheme);
+import { EscrowScheme } from '@agentokratia/x402-escrow/client';
+
+// Selector that prefers exact scheme over escrow
+const preferExactSelector = (version, requirements) => {
+  const exact = requirements.find((r) => r.scheme === 'exact');
+  return exact || requirements[0];
+};
+
+// Policy that filters by input token
+function createInputTokenPolicy(inputToken: string) {
+  return (version, requirements) => {
+    return requirements.filter((req) => {
+      if (req.scheme === 'exact') {
+        return req.asset?.toLowerCase() === inputToken.toLowerCase();
+      }
+      // For escrow, check swapData.inputToken
+      const swapData = req.extra?.swapData;
+      if (swapData?.inputToken) {
+        return swapData.inputToken.toLowerCase() === inputToken.toLowerCase();
+      }
+      return req.asset?.toLowerCase() === inputToken.toLowerCase();
+    });
+  };
+}
+
+// Create client with selector
+const client = new x402Client(preferExactSelector);
+
+// Register policy to filter by selected token
+client.registerPolicy(createInputTokenPolicy('0x4200000000000000000000000000000000000006')); // WETH
+
+// Register schemes
+client.register('eip155:8453', new ExactEvmScheme(signer));
+client.register('eip155:8453', new EscrowScheme(walletClient));
 ```
 
 ## Server Usage
 
 For APIs accepting payments. Config is auto-discovered from facilitator.
 
-### Express
+### Basic Setup
 
 ```typescript
 import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
-import { paymentMiddleware } from '@x402/express';
 import { EscrowScheme } from '@agentokratia/x402-escrow/server';
+import { ExactEvmScheme } from '@x402/evm/exact/server';
 
+// 1. Create facilitator client
 const facilitator = new HTTPFacilitatorClient({
   url: 'https://facilitator.agentokratia.com',
   createAuthHeaders: async () => ({
     verify: { Authorization: `Bearer ${process.env.X402_API_KEY}` },
     settle: { Authorization: `Bearer ${process.env.X402_API_KEY}` },
-    supported: {},
+    supported: { Authorization: `Bearer ${process.env.X402_API_KEY}` },
   }),
 });
 
-const server = new x402ResourceServer(facilitator).register('eip155:84532', new EscrowScheme());
-
-app.use(
-  paymentMiddleware(
-    {
-      'GET /api/premium': {
-        accepts: {
-          scheme: 'escrow',
-          price: '$0.01',
-          network: 'eip155:84532',
-          payTo: ownerAddress,
-        },
-      },
-    },
-    server
-  )
-);
+// 2. Create escrow scheme (for swap payments)
+const escrow = new EscrowScheme({
+  facilitator,
+  apiKey: process.env.X402_API_KEY,
+});
+
+// 3. Create x402 server with both schemes
+const server = new x402ResourceServer(facilitator);
+server.register('eip155:8453', new ExactEvmScheme()); // Direct USDC
+server.register('eip155:8453', escrow); // Swaps
 ```
 
-### Next.js
+### Building Payment Requirements (402 Response)
 
 ```typescript
-import { paymentProxy } from '@x402/next';
-import { EscrowScheme } from '@agentokratia/x402-escrow/server';
+// Build accepts for both schemes in parallel
+const [exactResult, escrowResult] = await Promise.allSettled([
+  // Exact scheme (USDC direct)
+  server.buildPaymentRequirements({
+    scheme: 'exact',
+    network: 'eip155:8453',
+    price: '$1.00',
+    payTo: recipientAddress,
+    maxTimeoutSeconds: 600,
+  }),
+  // Escrow scheme (swaps) - fetches DEX quotes
+  escrow.buildAcceptsResolved({
+    network: 'eip155:8453',
+    price: '$1.00',
+    payTo: recipientAddress,
+  }),
+]);
+
+// Combine into payment requirements array
+const paymentRequirements = [];
+
+if (exactResult.status === 'fulfilled') {
+  paymentRequirements.push(...exactResult.value);
+}
+
+if (escrowResult.status === 'fulfilled') {
+  for (const accept of escrowResult.value) {
+    paymentRequirements.push({
+      scheme: accept.scheme,
+      network: accept.network,
+      asset: accept.price.asset,
+      amount: accept.price.amount,
+      payTo: accept.payTo,
+      maxTimeoutSeconds: accept.maxTimeoutSeconds || 600,
+      extra: accept.price.extra || {},
+    });
+  }
+}
+
+// Return 402 with PAYMENT-REQUIRED header
+const encoded = Buffer.from(JSON.stringify(paymentRequirements)).toString('base64');
+response.headers.set('PAYMENT-REQUIRED', encoded);
+```
+
+### Processing Payments (Verify & Settle)
 
-const server = new x402ResourceServer(facilitator).register('eip155:84532', new EscrowScheme());
+```typescript
+import { preprocessSwapPayload } from '@agentokratia/x402-escrow/server';
+
+// Decode payment from PAYMENT-SIGNATURE header
+const paymentPayload = JSON.parse(Buffer.from(paymentSignature, 'base64').toString());
+
+// Decompress swap calldata before forwarding to facilitator
+// (Server compresses in buildAccepts, client passes through compressed)
+const processedPayload = preprocessSwapPayload({
+  x402Version: 2,
+  resource: { url: '/api/endpoint', mimeType: 'application/json' },
+  accepted: paymentPayload.accepted,
+  payload: paymentPayload.payload,
+});
+
+// Verify and settle with facilitator
+const verifyResult = await facilitator.verify(processedPayload, processedPayload.accepted);
+if (!verifyResult.isValid) {
+  throw new Error(verifyResult.invalidReason);
+}
+
+const settleResult = await facilitator.settle(processedPayload, processedPayload.accepted);
+if (!settleResult.success) {
+  throw new Error(settleResult.errorReason);
+}
 
-export const proxy = paymentProxy(
-  {
-    '/api/premium': {
-      accepts: { scheme: 'escrow', network: 'eip155:84532', payTo: ownerAddress, price: '$0.01' },
-    },
-  },
-  server
-);
+// Return success with transaction hash
+return { success: true, transaction: settleResult.transaction };
 ```
 
 ## How It Works
 
 ```
-1. User signs ERC-3009 authorization (gasless)
-2. Facilitator deposits funds to escrow contract
-3. Session created with balance
-4. Each API call debits from session (no signature needed)
-5. User can reclaim unused funds anytime
+Client                          Server                      Facilitator
+  │                               │                              │
+  │ GET /api/resource             │                              │
+  │──────────────────────────────>│                              │
+  │                               │ buildAccepts()               │
+  │                               │─────────────────────────────>│
+  │                               │ (fetches quotes for swaps)   │
+  │                               │<─────────────────────────────│
+  │   402 + PAYMENT-REQUIRED      │                              │
+  │<──────────────────────────────│                              │
+  │                               │                              │
+  │ User selects token (WETH)     │                              │
+  │ Signs EIP-712 Permit2         │                              │
+  │                               │                              │
+  │ GET + PAYMENT-SIGNATURE       │                              │
+  │──────────────────────────────>│                              │
+  │                               │ verify() + settle()          │
+  │                               │─────────────────────────────>│
+  │                               │   (executes swap on-chain)   │
+  │                               │<─────────────────────────────│
+  │  200 + transaction hash       │                              │
+  │<──────────────────────────────│                              │
 ```
 
 ## Networks
 
-| Network      | Chain ID | Escrow Contract                              |
-| ------------ | -------- | -------------------------------------------- |
-| Base Mainnet | 8453     | `0xbDEa0d1BCc5966192b070fDF62ab4eF5B4420Cff` |
-| Base Sepolia | 84532    | `0xbDEa0d1BCc5966192b070fDF62ab4eF5B4420Cff` |
+| Network      | Chain ID | Facilitator                            |
+| ------------ | -------- | -------------------------------------- |
+| Base Mainnet | 8453     | `https://facilitator.agentokratia.com` |
+| Base Sepolia | 84532    | `https://facilitator.agentokratia.com` |
 
 ## API
 
-### Client
-
-| Export                                      | Description                                   |
-| ------------------------------------------- | --------------------------------------------- |
-| `createEscrowFetch(walletClient, options?)` | Creates fetch with automatic payment handling |
-| `EscrowScheme`                              | Core scheme class for x402Client              |
-| `withSessionExtraction(fetch, scheme)`      | Wrapper to extract sessions from responses    |
-| `withAxiosSessionExtraction(scheme)`        | Axios interceptor for session extraction      |
-
-### Server
-
-| Export                  | Description                          |
-| ----------------------- | ------------------------------------ |
-| `EscrowScheme`          | Server scheme for x402ResourceServer |
-| `HTTPFacilitatorClient` | Re-export from @x402/core            |
+### Client Exports
+
+| Export                    | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `EscrowScheme`            | Client scheme for x402Client (takes WalletClient) |
+| `signERC3009`             | Sign ERC-3009 authorization                       |
+| `signPermit2TransferFrom` | Sign Permit2 transfer                             |
+| `computePaymentNonce`     | Derive deterministic nonce from payment params    |
+| `PERMIT2_ADDRESS`         | Universal Permit2 contract address                |
+| `decompressCalldata`      | Decompress gzipped aggregator calldata            |
+
+### Server Exports
+
+| Export                  | Description                                       |
+| ----------------------- | ------------------------------------------------- |
+| `EscrowScheme`          | Server scheme for x402ResourceServer              |
+| `HTTPFacilitatorClient` | Re-export from @x402/core/server                  |
+| `preprocessSwapPayload` | Decompress swap calldata before facilitator calls |
+| `compressCalldata`      | Compress aggregator calldata (gzip)               |
+
+## Supported Input Tokens (Base Mainnet)
+
+| Token | Address                                      |
+| ----- | -------------------------------------------- |
+| USDC  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| WETH  | `0x4200000000000000000000000000000000000006` |
+| DAI   | `0x50c5725949a6f0c72e6c4a641f24049a917db0cb` |
+| USDT  | `0xfde4c96c8593536e31f229ea8f37b2ada2699bb2` |
 
 ## License