@agentokratia/x402-escrow 2.1.1 → 2.1.2

package/README.md

@@ -5,208 +5,219 @@ Escrow payment scheme for the x402 protocol. Supports direct USDC payments and c
 ## Features
 
 - **Direct USDC payments** - Gasless via ERC-3009 ReceiveWithAuthorization
-- **Multi-token support** - Pay with WETH, DAI, USDT → receiver gets USDC
+- **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
 
 ```bash
-npm install @agentokratia/x402-escrow
+npm install @x402/core @x402/next @x402/fetch @x402/evm @agentokratia/x402-escrow viem
 ```
 
-## Client Usage
+## Server Integration
 
-For apps and agents paying for APIs.
-
-### Basic Setup
+### Next.js with paymentProxy
 
 ```typescript
-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);
-
-// Create payment payload from 402 response
-const paymentPayload = await client.createPaymentPayload(paymentRequired);
-```
-
-### With Policies (Token Selection)
+import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
+import { ExactEvmScheme } from '@x402/evm/exact/server';
+import { EscrowScheme } from '@agentokratia/x402-escrow/server';
+import { paymentProxy } from '@x402/next';
 
-```typescript
-import { x402Client } from '@x402/core/client';
-import { EscrowScheme } from '@agentokratia/x402-escrow/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}` },
+  }),
+});
 
-// Selector that prefers exact scheme over escrow
-const preferExactSelector = (version, requirements) => {
-  const exact = requirements.find((r) => r.scheme === 'exact');
-  return exact || requirements[0];
-};
+const escrow = new EscrowScheme({ facilitator });
 
-// 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();
-    });
-  };
-}
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
 
-// Create client with selector
-const client = new x402Client(preferExactSelector);
+const server = new x402ResourceServer(facilitator)
+  .register('eip155:8453', new ExactEvmScheme())
+  .register('eip155:8453', escrow);
 
-// Register policy to filter by selected token
-client.registerPolicy(createInputTokenPolicy('0x4200000000000000000000000000000000000006')); // WETH
+// Auto-discovers supported tokens (USDC, WETH, DAI...)
+const escrowAccepts = await escrow.buildAccepts({
+  network: 'eip155:8453',
+  price: '$0.01',
+  payTo: '0xYourWallet...',
+  asset: USDC, // settlement token (default: auto-detect)
+});
 
-// Register schemes
-client.register('eip155:8453', new ExactEvmScheme(signer));
-client.register('eip155:8453', new EscrowScheme(walletClient));
+export const middleware = paymentProxy(
+  {
+    '/api/premium': {
+      accepts: [
+        { scheme: 'exact', network: 'eip155:8453', price: '$0.01', payTo: '0xYourWallet...' },
+        ...escrowAccepts,
+      ],
+    },
+  },
+  server
+);
 ```
 
-## Server Usage
-
-For APIs accepting payments. Config is auto-discovered from facilitator.
-
-### Basic Setup
+### Express with paymentMiddleware
 
 ```typescript
+import { paymentMiddleware } from '@x402/express';
 import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
 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: { Authorization: `Bearer ${process.env.X402_API_KEY}` },
   }),
 });
 
-// 2. Create escrow scheme (for swap payments)
-const escrow = new EscrowScheme({
-  facilitator,
-  apiKey: process.env.X402_API_KEY,
+const escrow = new EscrowScheme({ facilitator });
+const accepts = await escrow.buildAccepts({
+  network: 'eip155:8453',
+  price: '$0.01',
+  payTo: '0xYourWallet',
 });
 
-// 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
+app.use(
+  paymentMiddleware(
+    {
+      'GET /api/analyze': { accepts },
+    },
+    new x402ResourceServer(facilitator)
+  )
+);
 ```
 
-### Building Payment Requirements (402 Response)
+### Dynamic Pricing (Custom API Routes)
+
+For endpoints with per-request pricing (like tip-app):
 
 ```typescript
-// 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,
-  }),
-]);
+import { NextRequest, NextResponse } from 'next/server';
+import { HTTPFacilitatorClient } from '@x402/core/server';
+import { EscrowScheme, preprocessSwapPayload } from '@agentokratia/x402-escrow/server';
 
-// Combine into payment requirements array
-const paymentRequirements = [];
+const facilitator = new HTTPFacilitatorClient({
+  /* config */
+});
+const escrow = new EscrowScheme({ facilitator, apiKey: process.env.X402_API_KEY });
+
+export async function GET(request: NextRequest) {
+  const amount = request.nextUrl.searchParams.get('amount');
+  const recipient = request.nextUrl.searchParams.get('to');
+  const paymentSignature = request.headers.get('payment-signature');
+
+  if (!paymentSignature) {
+    // Fetch fresh DEX quotes with buildAcceptsResolved
+    const accepts = await escrow.buildAcceptsResolved({
+      network: 'eip155:8453',
+      price: `$${amount}`,
+      payTo: recipient,
+    });
 
-if (exactResult.status === 'fulfilled') {
-  paymentRequirements.push(...exactResult.value);
-}
+    const requirements = accepts.map((a) => ({
+      scheme: a.scheme,
+      network: a.network,
+      asset: a.price.asset,
+      amount: a.price.amount,
+      payTo: a.payTo,
+      maxTimeoutSeconds: 600,
+      extra: a.price.extra || {},
+    }));
+
+    const response = NextResponse.json({ message: 'Payment required' }, { status: 402 });
+    response.headers.set(
+      'PAYMENT-REQUIRED',
+      Buffer.from(JSON.stringify(requirements)).toString('base64')
+    );
+    return response;
+  }
 
-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 || {},
-    });
+  // Process payment
+  const payload = JSON.parse(Buffer.from(paymentSignature, 'base64').toString());
+  const processed = preprocessSwapPayload({ x402Version: 2, ...payload });
+
+  const verifyResult = await facilitator.verify(processed, processed.accepted);
+  if (!verifyResult.isValid) {
+    return NextResponse.json({ error: verifyResult.invalidReason }, { status: 402 });
   }
-}
 
-// Return 402 with PAYMENT-REQUIRED header
-const encoded = Buffer.from(JSON.stringify(paymentRequirements)).toString('base64');
-response.headers.set('PAYMENT-REQUIRED', encoded);
+  const settleResult = await facilitator.settle(processed, processed.accepted);
+  return NextResponse.json({ success: true, transaction: settleResult.transaction });
+}
 ```
 
-### Processing Payments (Verify & Settle)
+## Client Integration
+
+### Balance-Aware Token Selection (Recommended)
 
 ```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,
+import { wrapFetchWithPayment, x402Client } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { createWalletClient, createPublicClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import {
+  EscrowScheme,
+  createBalanceSelector,
+  preferTokenPolicy,
+} from '@agentokratia/x402-escrow/client';
+
+const WETH = '0x4200000000000000000000000000000000000006';
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY);
+
+const walletClient = createWalletClient({
+  account,
+  chain: base,
+  transport: http(),
 });
 
-// Verify and settle with facilitator
-const verifyResult = await facilitator.verify(processedPayload, processedPayload.accepted);
-if (!verifyResult.isValid) {
-  throw new Error(verifyResult.invalidReason);
-}
+const publicClient = createPublicClient({
+  chain: base,
+  transport: http(),
+});
 
-const settleResult = await facilitator.settle(processedPayload, processedPayload.accepted);
-if (!settleResult.success) {
-  throw new Error(settleResult.errorReason);
-}
+// Balance-aware: auto-picks USDC (gasless) or WETH/DAI (swap)
+const client = new x402Client(createBalanceSelector(publicClient, account.address))
+  .register('eip155:8453', new ExactEvmScheme(account))
+  .register('eip155:8453', new EscrowScheme(walletClient))
+  .registerPolicy(preferTokenPolicy([WETH, USDC]));
+
+const paidFetch = wrapFetchWithPayment(fetch, client);
+
+const res = await paidFetch('https://api.example.com/premium');
+const data = await res.json();
+```
+
+### Simple Setup (Browser with wagmi)
+
+```typescript
+import { wrapFetchWithPayment, x402Client } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { EscrowScheme } from '@agentokratia/x402-escrow/client';
+
+// With wagmi's useWalletClient
+const { data: walletClient } = useWalletClient();
+
+const signer = {
+  address: walletClient.account.address,
+  signTypedData: (msg) => walletClient.signTypedData({ account: walletClient.account, ...msg }),
+};
+
+const client = new x402Client()
+  .register('eip155:8453', new ExactEvmScheme(signer))
+  .register('eip155:8453', new EscrowScheme(walletClient));
 
-// Return success with transaction hash
-return { success: true, transaction: settleResult.transaction };
+const paidFetch = wrapFetchWithPayment(fetch, client);
+const res = await paidFetch('https://api.example.com/premium');
 ```
 
 ## How It Works
@@ -250,6 +261,9 @@ Client                          Server                      Facilitator
 | Export                    | Description                                       |
 | ------------------------- | ------------------------------------------------- |
 | `EscrowScheme`            | Client scheme for x402Client (takes WalletClient) |
+| `createBalanceSelector`   | Async selector that checks on-chain balances      |
+| `preferTokenPolicy`       | Sync policy that reorders by token preference     |
+| `checkBalance`            | Utility for custom balance checks                 |
 | `signERC3009`             | Sign ERC-3009 authorization                       |
 | `signPermit2TransferFrom` | Sign Permit2 transfer                             |
 | `computePaymentNonce`     | Derive deterministic nonce from payment params    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentokratia/x402-escrow",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Escrow payment scheme for x402 protocol - session-based payments for high-frequency APIs",
   "license": "MIT",
   "author": "Agentokratia",