@wtflabs/x402-fetch 0.0.1-beta.0

package/README.md

@@ -0,0 +1,210 @@
+# x402-fetch
+
+A utility package that extends the native `fetch` API to automatically handle 402 Payment Required responses using the x402 payment protocol. This package enables seamless integration of payment functionality into your applications when making HTTP requests.
+
+## Supported Authorization Types
+
+This package supports multiple EVM authorization standards:
+
+- **EIP-3009** (default): `transferWithAuthorization` - gasless token transfers
+- **EIP-2612 Permit**: Standard permit functionality for ERC-20 tokens
+- **Permit2**: Uniswap's universal token approval system
+
+The authorization type is automatically selected based on the server's payment requirements (`paymentType` field).
+
+## Installation
+
+```bash
+npm install x402-fetch
+```
+
+## Quick Start
+
+```typescript
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { wrapFetchWithPayment } from "x402-fetch";
+import { baseSepolia } from "viem/chains";
+
+// Create a wallet client
+const account = privateKeyToAccount("0xYourPrivateKey");
+const client = createWalletClient({
+  account,
+  transport: http(),
+  chain: baseSepolia,
+});
+
+// Wrap the fetch function with payment handling
+const fetchWithPay = wrapFetchWithPayment(fetch, client);
+
+// Make a request that may require payment
+const response = await fetchWithPay("https://api.example.com/paid-endpoint", {
+  method: "GET",
+});
+
+const data = await response.json();
+```
+
+## 多链支持
+
+x402-fetch 现在支持灵活的多 EVM 链配置！使用新的 `createEvmSigner` API：
+
+```typescript
+import { createEvmSigner, wrapFetchWithPayment } from 'x402-fetch';
+
+// 方式 1：使用链名称
+const bscSigner = createEvmSigner('bsc', '0xYourPrivateKey');
+
+// 方式 2：使用 viem chain 对象
+import { polygon } from 'viem/chains';
+const polygonSigner = createEvmSigner(polygon, '0xYourPrivateKey');
+
+// 方式 3：自定义配置（包括自定义 RPC）
+const customSigner = createEvmSigner({
+  chainId: 56,
+  name: 'BSC',
+  rpcUrl: 'https://my-custom-rpc.com',
+}, '0xYourPrivateKey');
+
+// 为每条链创建独立的 fetch wrapper
+const fetchBsc = wrapFetchWithPayment(fetch, bscSigner);
+const fetchPolygon = wrapFetchWithPayment(fetch, polygonSigner);
+```
+
+**[📖 查看完整的多链使用指南](./MULTI_CHAIN_USAGE.md)**
+
+## API
+
+### `wrapFetchWithPayment(fetch, walletClient, maxValue?, paymentRequirementsSelector?)`
+
+Wraps the native fetch API to handle 402 Payment Required responses automatically.
+
+#### Parameters
+
+- `fetch`: The fetch function to wrap (typically `globalThis.fetch`)
+- `walletClient`: The wallet client used to sign payment messages (must implement the x402 wallet interface)
+- `maxValue`: Optional maximum allowed payment amount in base units (defaults to 0.1 USDC)
+- `paymentRequirementsSelector`: Optional function to select payment requirements from the response (defaults to `selectPaymentRequirements`)
+
+#### Returns
+
+A wrapped fetch function that automatically handles 402 responses by:
+1. Making the initial request
+2. If a 402 response is received, parsing the payment requirements
+3. Verifying the payment amount is within the allowed maximum
+4. Creating a payment header using the provided wallet client
+5. Retrying the request with the payment header
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { config } from "dotenv";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { wrapFetchWithPayment } from "x402-fetch";
+import { baseSepolia } from "viem/chains";
+
+config();
+
+const { PRIVATE_KEY, API_URL } = process.env;
+
+const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);
+const client = createWalletClient({
+  account,
+  transport: http(),
+  chain: baseSepolia,
+});
+
+const fetchWithPay = wrapFetchWithPayment(fetch, client);
+
+// Make a request to a paid API endpoint
+fetchWithPay(API_URL, {
+  method: "GET",
+})
+  .then(async response => {
+    const data = await response.json();
+    console.log(data);
+  })
+  .catch(error => {
+    console.error(error);
+  });
+```
+
+### Server-Side: Specifying Payment Type
+
+The server specifies which payment type the client should use in the 402 response:
+
+```typescript
+// EIP-2612 Permit example
+app.post("/api/protected", async (c) => {
+  const paymentHeader = c.req.header("X-PAYMENT");
+  
+  if (!paymentHeader) {
+    return c.json({
+      x402Version: 1,
+      accepts: [{
+        scheme: "exact",
+        network: "base-sepolia",
+        maxAmountRequired: "100000",
+        resource: "http://localhost:3000/api/protected",
+        description: "Access to protected resource",
+        mimeType: "application/json",
+        payTo: "0x...",
+        maxTimeoutSeconds: 3600,
+        asset: "0x...", // Token address
+        paymentType: "permit", // Specify permit
+      }]
+    }, 402);
+  }
+  
+  // Verify and settle payment...
+});
+```
+
+```typescript
+// Permit2 example
+app.post("/api/protected", async (c) => {
+  const paymentHeader = c.req.header("X-PAYMENT");
+  
+  if (!paymentHeader) {
+    return c.json({
+      x402Version: 1,
+      accepts: [{
+        scheme: "exact",
+        network: "base-sepolia",
+        maxAmountRequired: "100000",
+        resource: "http://localhost:3000/api/protected",
+        description: "Access to protected resource",
+        mimeType: "application/json",
+        payTo: "0x...",
+        maxTimeoutSeconds: 3600,
+        asset: "0x...", // Token address
+        paymentType: "permit2", // Specify permit2
+      }]
+    }, 402);
+  }
+  
+  // Verify and settle payment...
+});
+```
+
+### Payment Type Selection
+
+The client automatically detects and uses the appropriate payment type:
+
+1. **Server specifies `paymentType: "permit"`** → Client uses EIP-2612 Permit
+2. **Server specifies `paymentType: "permit2"`** → Client uses Permit2
+3. **Server specifies `paymentType: "eip3009"` or omits it** → Client uses EIP-3009 (default)
+
+### Authorization Type Comparison
+
+| Feature | EIP-3009 | EIP-2612 Permit | Permit2 |
+|---------|----------|-----------------|---------|
+| Gas efficiency | High | High | High |
+| Token support | Limited (tokens with EIP-3009) | Wide (most ERC-20) | Universal |
+| Approval management | Per-transaction | Per-spender | Universal router |
+| Nonce management | Custom | On-chain | Advanced |
+| Best for | Specialized tokens | Standard ERC-20 | DeFi integrations |
+

package/dist/cjs/index.d.ts

@@ -0,0 +1,48 @@
+import { Signer, MultiNetworkSigner, X402Config } from 'x402/types';
+export { ConnectedClient, EvmChainConfig, MultiNetworkSigner, Signer, X402Config, createConnectedClient, createSigner, withChain } from 'x402/types';
+import { PaymentRequirementsSelector } from 'x402/client';
+export { PaymentRequirementsSelector } from 'x402/client';
+export { decodeXPaymentResponse } from 'x402/shared';
+export { Chain, Hex } from 'viem';
+
+/**
+ * Enables the payment of APIs using the x402 payment protocol.
+ *
+ * This function wraps the native fetch API to automatically handle 402 Payment Required responses
+ * by creating and sending a payment header. It will:
+ * 1. Make the initial request
+ * 2. If a 402 response is received, parse the payment requirements
+ * 3. Verify the payment amount is within the allowed maximum
+ * 4. Create a payment header using the provided wallet client
+ * 5. Retry the request with the payment header
+ *
+ * @param fetch - The fetch function to wrap (typically globalThis.fetch)
+ * @param walletClient - The wallet client used to sign payment messages
+ * @param maxValue - The maximum allowed payment amount in base units (defaults to 0.1 USDC)
+ * @param paymentRequirementsSelector - A function that selects the payment requirements from the response
+ * @param config - Optional configuration for X402 operations (e.g., custom RPC URLs)
+ * @returns A wrapped fetch function that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * const wallet = new SignerWallet(...);
+ * const fetchWithPay = wrapFetchWithPayment(fetch, wallet);
+ *
+ * // With custom RPC configuration
+ * const fetchWithPay = wrapFetchWithPayment(fetch, wallet, undefined, undefined, {
+ *   svmConfig: { rpcUrl: "http://localhost:8899" }
+ * });
+ *
+ * // Make a request that may require payment
+ * const response = await fetchWithPay('https://api.example.com/paid-endpoint');
+ * ```
+ *
+ * @throws {Error} If the payment amount exceeds the maximum allowed value
+ * @throws {Error} If the request configuration is missing
+ * @throws {Error} If a payment has already been attempted for this request
+ * @throws {Error} If there's an error creating the payment header
+ */
+declare function wrapFetchWithPayment(fetch: typeof globalThis.fetch, walletClient: Signer | MultiNetworkSigner, maxValue?: bigint, // Default to 0.10 USDC
+paymentRequirementsSelector?: PaymentRequirementsSelector, config?: X402Config): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+
+export { wrapFetchWithPayment };

package/dist/cjs/index.js

@@ -0,0 +1,111 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createConnectedClient: () => import_types2.createConnectedClient,
+  createSigner: () => import_types2.createSigner,
+  decodeXPaymentResponse: () => import_shared.decodeXPaymentResponse,
+  withChain: () => import_types2.withChain,
+  wrapFetchWithPayment: () => wrapFetchWithPayment
+});
+module.exports = __toCommonJS(src_exports);
+var import_types = require("x402/types");
+var import_client = require("x402/client");
+var import_schemes = require("x402/schemes");
+var import_shared = require("x402/shared");
+var import_types2 = require("x402/types");
+function wrapFetchWithPayment(fetch, walletClient, maxValue = BigInt(0.1 * 10 ** 6), paymentRequirementsSelector = import_client.selectPaymentRequirements, config) {
+  return async (input, init) => {
+    var _a;
+    const response = await fetch(input, init);
+    if (response.status !== 402) {
+      return response;
+    }
+    const { x402Version, accepts } = await response.json();
+    const parsedPaymentRequirements = accepts.map((x) => import_types.PaymentRequirementsSchema.parse(x));
+    const network = (0, import_types.isMultiNetworkSigner)(walletClient) ? void 0 : import_types.evm.isSignerWallet(walletClient) ? import_types.ChainIdToNetwork[(_a = walletClient.chain) == null ? void 0 : _a.id] : (0, import_types.isSvmSignerWallet)(walletClient) ? ["solana", "solana-devnet"] : void 0;
+    const selectedPaymentRequirements = paymentRequirementsSelector(
+      parsedPaymentRequirements,
+      network,
+      "exact"
+    );
+    if (BigInt(selectedPaymentRequirements.maxAmountRequired) > maxValue) {
+      throw new Error("Payment amount exceeds maximum allowed");
+    }
+    const paymentType = selectedPaymentRequirements.paymentType || "eip3009";
+    let paymentHeader;
+    const isEvmNetwork = network && !["solana", "solana-devnet"].includes(network[0]);
+    if (paymentType === "permit" && isEvmNetwork) {
+      if (!import_types.evm.isSignerWallet(walletClient)) {
+        throw new Error("Permit authorization requires an EVM signer wallet");
+      }
+      paymentHeader = await import_schemes.exact.evm.permit.createPaymentHeader(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements
+      );
+    } else if (paymentType === "permit2" && isEvmNetwork) {
+      if (!import_types.evm.isSignerWallet(walletClient)) {
+        throw new Error("Permit2 authorization requires an EVM signer wallet");
+      }
+      paymentHeader = await import_schemes.exact.evm.permit2.createPaymentHeader(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements
+      );
+    } else if (paymentType === "eip3009" || !paymentType) {
+      paymentHeader = await (0, import_client.createPaymentHeader)(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements,
+        config
+      );
+    } else {
+      throw new Error(`Unsupported payment type: ${paymentType}`);
+    }
+    if (!init) {
+      throw new Error("Missing fetch request configuration");
+    }
+    if (init.__is402Retry) {
+      throw new Error("Payment already attempted");
+    }
+    const newInit = {
+      ...init,
+      headers: {
+        ...init.headers || {},
+        "X-PAYMENT": paymentHeader,
+        "Access-Control-Expose-Headers": "X-PAYMENT-RESPONSE"
+      },
+      __is402Retry: true
+    };
+    const secondResponse = await fetch(input, newInit);
+    return secondResponse;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createConnectedClient,
+  createSigner,
+  decodeXPaymentResponse,
+  withChain,
+  wrapFetchWithPayment
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["import {\n  ChainIdToNetwork,\n  PaymentRequirementsSchema,\n  Signer,\n  evm,\n  MultiNetworkSigner,\n  isMultiNetworkSigner,\n  isSvmSignerWallet,\n  Network,\n  X402Config,\n} from \"x402/types\";\nimport {\n  createPaymentHeader,\n  PaymentRequirementsSelector,\n  selectPaymentRequirements,\n} from \"x402/client\";\nimport { exact } from \"x402/schemes\";\n\n/**\n * Enables the payment of APIs using the x402 payment protocol.\n *\n * This function wraps the native fetch API to automatically handle 402 Payment Required responses\n * by creating and sending a payment header. It will:\n * 1. Make the initial request\n * 2. If a 402 response is received, parse the payment requirements\n * 3. Verify the payment amount is within the allowed maximum\n * 4. Create a payment header using the provided wallet client\n * 5. Retry the request with the payment header\n *\n * @param fetch - The fetch function to wrap (typically globalThis.fetch)\n * @param walletClient - The wallet client used to sign payment messages\n * @param maxValue - The maximum allowed payment amount in base units (defaults to 0.1 USDC)\n * @param paymentRequirementsSelector - A function that selects the payment requirements from the response\n * @param config - Optional configuration for X402 operations (e.g., custom RPC URLs)\n * @returns A wrapped fetch function that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * const wallet = new SignerWallet(...);\n * const fetchWithPay = wrapFetchWithPayment(fetch, wallet);\n *\n * // With custom RPC configuration\n * const fetchWithPay = wrapFetchWithPayment(fetch, wallet, undefined, undefined, {\n *   svmConfig: { rpcUrl: \"http://localhost:8899\" }\n * });\n *\n * // Make a request that may require payment\n * const response = await fetchWithPay('https://api.example.com/paid-endpoint');\n * ```\n *\n * @throws {Error} If the payment amount exceeds the maximum allowed value\n * @throws {Error} If the request configuration is missing\n * @throws {Error} If a payment has already been attempted for this request\n * @throws {Error} If there's an error creating the payment header\n */\nexport function wrapFetchWithPayment(\n  fetch: typeof globalThis.fetch,\n  walletClient: Signer | MultiNetworkSigner,\n  maxValue: bigint = BigInt(0.1 * 10 ** 6), // Default to 0.10 USDC\n  paymentRequirementsSelector: PaymentRequirementsSelector = selectPaymentRequirements,\n  config?: X402Config,\n) {\n  return async (input: RequestInfo, init?: RequestInit) => {\n    const response = await fetch(input, init);\n\n    if (response.status !== 402) {\n      return response;\n    }\n\n    const { x402Version, accepts } = (await response.json()) as {\n      x402Version: number;\n      accepts: unknown[];\n    };\n    const parsedPaymentRequirements = accepts.map(x => PaymentRequirementsSchema.parse(x));\n\n    const network = isMultiNetworkSigner(walletClient)\n      ? undefined\n      : evm.isSignerWallet(walletClient as typeof evm.EvmSigner)\n        ? ChainIdToNetwork[(walletClient as typeof evm.EvmSigner).chain?.id]\n        : isSvmSignerWallet(walletClient)\n          ? ([\"solana\", \"solana-devnet\"] as Network[])\n          : undefined;\n\n    const selectedPaymentRequirements = paymentRequirementsSelector(\n      parsedPaymentRequirements,\n      network,\n      \"exact\",\n    );\n\n    if (BigInt(selectedPaymentRequirements.maxAmountRequired) > maxValue) {\n      throw new Error(\"Payment amount exceeds maximum allowed\");\n    }\n\n    // 获取支付类型，默认为 eip3009\n    const paymentType = selectedPaymentRequirements.paymentType || \"eip3009\";\n\n    // 根据支付类型创建支付头\n    let paymentHeader: string;\n\n    // 仅对 EVM 网络支持 permit 和 permit2\n    const isEvmNetwork = network && ![\"solana\", \"solana-devnet\"].includes(network[0]);\n\n    if (paymentType === \"permit\" && isEvmNetwork) {\n      // 使用 EIP-2612 Permit\n      if (!evm.isSignerWallet(walletClient as typeof evm.EvmSigner)) {\n        throw new Error(\"Permit authorization requires an EVM signer wallet\");\n      }\n      paymentHeader = await exact.evm.permit.createPaymentHeader(\n        walletClient as typeof evm.EvmSigner,\n        x402Version,\n        selectedPaymentRequirements,\n      );\n    } else if (paymentType === \"permit2\" && isEvmNetwork) {\n      // 使用 Permit2\n      if (!evm.isSignerWallet(walletClient as typeof evm.EvmSigner)) {\n        throw new Error(\"Permit2 authorization requires an EVM signer wallet\");\n      }\n      paymentHeader = await exact.evm.permit2.createPaymentHeader(\n        walletClient as typeof evm.EvmSigner,\n        x402Version,\n        selectedPaymentRequirements,\n      );\n    } else if (paymentType === \"eip3009\" || !paymentType) {\n      // 默认使用 EIP-3009（统一的 createPaymentHeader）\n      paymentHeader = await createPaymentHeader(\n        walletClient,\n        x402Version,\n        selectedPaymentRequirements,\n        config,\n      );\n    } else {\n      throw new Error(`Unsupported payment type: ${paymentType}`);\n    }\n\n    if (!init) {\n      throw new Error(\"Missing fetch request configuration\");\n    }\n\n    if ((init as { __is402Retry?: boolean }).__is402Retry) {\n      throw new Error(\"Payment already attempted\");\n    }\n\n    const newInit = {\n      ...init,\n      headers: {\n        ...(init.headers || {}),\n        \"X-PAYMENT\": paymentHeader,\n        \"Access-Control-Expose-Headers\": \"X-PAYMENT-RESPONSE\",\n      },\n      __is402Retry: true,\n    };\n\n    const secondResponse = await fetch(input, newInit);\n    return secondResponse;\n  };\n}\n\nexport { decodeXPaymentResponse } from \"x402/shared\";\nexport {\n  createSigner,\n  createConnectedClient,\n  withChain,\n  type Signer,\n  type ConnectedClient,\n  type MultiNetworkSigner,\n  type X402Config,\n  type EvmChainConfig\n} from \"x402/types\";\nexport { type PaymentRequirementsSelector } from \"x402/client\";\nexport type { Hex, Chain } from \"viem\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAUO;AACP,oBAIO;AACP,qBAAsB;AA6ItB,oBAAuC;AACvC,IAAAA,gBASO;AAhHA,SAAS,qBACd,OACA,cACA,WAAmB,OAAO,MAAM,MAAM,CAAC,GACvC,8BAA2D,yCAC3D,QACA;AACA,SAAO,OAAO,OAAoB,SAAuB;AA9D3D;AA+DI,UAAM,WAAW,MAAM,MAAM,OAAO,IAAI;AAExC,QAAI,SAAS,WAAW,KAAK;AAC3B,aAAO;AAAA,IACT;AAEA,UAAM,EAAE,aAAa,QAAQ,IAAK,MAAM,SAAS,KAAK;AAItD,UAAM,4BAA4B,QAAQ,IAAI,OAAK,uCAA0B,MAAM,CAAC,CAAC;AAErF,UAAM,cAAU,mCAAqB,YAAY,IAC7C,SACA,iBAAI,eAAe,YAAoC,IACrD,+BAAkB,kBAAsC,UAAtC,mBAA6C,EAAE,QACjE,gCAAkB,YAAY,IAC3B,CAAC,UAAU,eAAe,IAC3B;AAER,UAAM,8BAA8B;AAAA,MAClC;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,QAAI,OAAO,4BAA4B,iBAAiB,IAAI,UAAU;AACpE,YAAM,IAAI,MAAM,wCAAwC;AAAA,IAC1D;AAGA,UAAM,cAAc,4BAA4B,eAAe;AAG/D,QAAI;AAGJ,UAAM,eAAe,WAAW,CAAC,CAAC,UAAU,eAAe,EAAE,SAAS,QAAQ,CAAC,CAAC;AAEhF,QAAI,gBAAgB,YAAY,cAAc;AAE5C,UAAI,CAAC,iBAAI,eAAe,YAAoC,GAAG;AAC7D,cAAM,IAAI,MAAM,oDAAoD;AAAA,MACtE;AACA,sBAAgB,MAAM,qBAAM,IAAI,OAAO;AAAA,QACrC;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,WAAW,gBAAgB,aAAa,cAAc;AAEpD,UAAI,CAAC,iBAAI,eAAe,YAAoC,GAAG;AAC7D,cAAM,IAAI,MAAM,qDAAqD;AAAA,MACvE;AACA,sBAAgB,MAAM,qBAAM,IAAI,QAAQ;AAAA,QACtC;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,WAAW,gBAAgB,aAAa,CAAC,aAAa;AAEpD,sBAAgB,UAAM;AAAA,QACpB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,OAAO;AACL,YAAM,IAAI,MAAM,6BAA6B,WAAW,EAAE;AAAA,IAC5D;AAEA,QAAI,CAAC,MAAM;AACT,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AAEA,QAAK,KAAoC,cAAc;AACrD,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC7C;AAEA,UAAM,UAAU;AAAA,MACd,GAAG;AAAA,MACH,SAAS;AAAA,QACP,GAAI,KAAK,WAAW,CAAC;AAAA,QACrB,aAAa;AAAA,QACb,iCAAiC;AAAA,MACnC;AAAA,MACA,cAAc;AAAA,IAChB;AAEA,UAAM,iBAAiB,MAAM,MAAM,OAAO,OAAO;AACjD,WAAO;AAAA,EACT;AACF;","names":["import_types"]}

package/dist/esm/index.d.mts

@@ -0,0 +1,48 @@
+import { Signer, MultiNetworkSigner, X402Config } from 'x402/types';
+export { ConnectedClient, EvmChainConfig, MultiNetworkSigner, Signer, X402Config, createConnectedClient, createSigner, withChain } from 'x402/types';
+import { PaymentRequirementsSelector } from 'x402/client';
+export { PaymentRequirementsSelector } from 'x402/client';
+export { decodeXPaymentResponse } from 'x402/shared';
+export { Chain, Hex } from 'viem';
+
+/**
+ * Enables the payment of APIs using the x402 payment protocol.
+ *
+ * This function wraps the native fetch API to automatically handle 402 Payment Required responses
+ * by creating and sending a payment header. It will:
+ * 1. Make the initial request
+ * 2. If a 402 response is received, parse the payment requirements
+ * 3. Verify the payment amount is within the allowed maximum
+ * 4. Create a payment header using the provided wallet client
+ * 5. Retry the request with the payment header
+ *
+ * @param fetch - The fetch function to wrap (typically globalThis.fetch)
+ * @param walletClient - The wallet client used to sign payment messages
+ * @param maxValue - The maximum allowed payment amount in base units (defaults to 0.1 USDC)
+ * @param paymentRequirementsSelector - A function that selects the payment requirements from the response
+ * @param config - Optional configuration for X402 operations (e.g., custom RPC URLs)
+ * @returns A wrapped fetch function that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * const wallet = new SignerWallet(...);
+ * const fetchWithPay = wrapFetchWithPayment(fetch, wallet);
+ *
+ * // With custom RPC configuration
+ * const fetchWithPay = wrapFetchWithPayment(fetch, wallet, undefined, undefined, {
+ *   svmConfig: { rpcUrl: "http://localhost:8899" }
+ * });
+ *
+ * // Make a request that may require payment
+ * const response = await fetchWithPay('https://api.example.com/paid-endpoint');
+ * ```
+ *
+ * @throws {Error} If the payment amount exceeds the maximum allowed value
+ * @throws {Error} If the request configuration is missing
+ * @throws {Error} If a payment has already been attempted for this request
+ * @throws {Error} If there's an error creating the payment header
+ */
+declare function wrapFetchWithPayment(fetch: typeof globalThis.fetch, walletClient: Signer | MultiNetworkSigner, maxValue?: bigint, // Default to 0.10 USDC
+paymentRequirementsSelector?: PaymentRequirementsSelector, config?: X402Config): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+
+export { wrapFetchWithPayment };

package/dist/esm/index.mjs

@@ -0,0 +1,95 @@
+// src/index.ts
+import {
+  ChainIdToNetwork,
+  PaymentRequirementsSchema,
+  evm,
+  isMultiNetworkSigner,
+  isSvmSignerWallet
+} from "x402/types";
+import {
+  createPaymentHeader,
+  selectPaymentRequirements
+} from "x402/client";
+import { exact } from "x402/schemes";
+import { decodeXPaymentResponse } from "x402/shared";
+import {
+  createSigner,
+  createConnectedClient,
+  withChain
+} from "x402/types";
+function wrapFetchWithPayment(fetch, walletClient, maxValue = BigInt(0.1 * 10 ** 6), paymentRequirementsSelector = selectPaymentRequirements, config) {
+  return async (input, init) => {
+    var _a;
+    const response = await fetch(input, init);
+    if (response.status !== 402) {
+      return response;
+    }
+    const { x402Version, accepts } = await response.json();
+    const parsedPaymentRequirements = accepts.map((x) => PaymentRequirementsSchema.parse(x));
+    const network = isMultiNetworkSigner(walletClient) ? void 0 : evm.isSignerWallet(walletClient) ? ChainIdToNetwork[(_a = walletClient.chain) == null ? void 0 : _a.id] : isSvmSignerWallet(walletClient) ? ["solana", "solana-devnet"] : void 0;
+    const selectedPaymentRequirements = paymentRequirementsSelector(
+      parsedPaymentRequirements,
+      network,
+      "exact"
+    );
+    if (BigInt(selectedPaymentRequirements.maxAmountRequired) > maxValue) {
+      throw new Error("Payment amount exceeds maximum allowed");
+    }
+    const paymentType = selectedPaymentRequirements.paymentType || "eip3009";
+    let paymentHeader;
+    const isEvmNetwork = network && !["solana", "solana-devnet"].includes(network[0]);
+    if (paymentType === "permit" && isEvmNetwork) {
+      if (!evm.isSignerWallet(walletClient)) {
+        throw new Error("Permit authorization requires an EVM signer wallet");
+      }
+      paymentHeader = await exact.evm.permit.createPaymentHeader(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements
+      );
+    } else if (paymentType === "permit2" && isEvmNetwork) {
+      if (!evm.isSignerWallet(walletClient)) {
+        throw new Error("Permit2 authorization requires an EVM signer wallet");
+      }
+      paymentHeader = await exact.evm.permit2.createPaymentHeader(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements
+      );
+    } else if (paymentType === "eip3009" || !paymentType) {
+      paymentHeader = await createPaymentHeader(
+        walletClient,
+        x402Version,
+        selectedPaymentRequirements,
+        config
+      );
+    } else {
+      throw new Error(`Unsupported payment type: ${paymentType}`);
+    }
+    if (!init) {
+      throw new Error("Missing fetch request configuration");
+    }
+    if (init.__is402Retry) {
+      throw new Error("Payment already attempted");
+    }
+    const newInit = {
+      ...init,
+      headers: {
+        ...init.headers || {},
+        "X-PAYMENT": paymentHeader,
+        "Access-Control-Expose-Headers": "X-PAYMENT-RESPONSE"
+      },
+      __is402Retry: true
+    };
+    const secondResponse = await fetch(input, newInit);
+    return secondResponse;
+  };
+}
+export {
+  createConnectedClient,
+  createSigner,
+  decodeXPaymentResponse,
+  withChain,
+  wrapFetchWithPayment
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["import {\n  ChainIdToNetwork,\n  PaymentRequirementsSchema,\n  Signer,\n  evm,\n  MultiNetworkSigner,\n  isMultiNetworkSigner,\n  isSvmSignerWallet,\n  Network,\n  X402Config,\n} from \"x402/types\";\nimport {\n  createPaymentHeader,\n  PaymentRequirementsSelector,\n  selectPaymentRequirements,\n} from \"x402/client\";\nimport { exact } from \"x402/schemes\";\n\n/**\n * Enables the payment of APIs using the x402 payment protocol.\n *\n * This function wraps the native fetch API to automatically handle 402 Payment Required responses\n * by creating and sending a payment header. It will:\n * 1. Make the initial request\n * 2. If a 402 response is received, parse the payment requirements\n * 3. Verify the payment amount is within the allowed maximum\n * 4. Create a payment header using the provided wallet client\n * 5. Retry the request with the payment header\n *\n * @param fetch - The fetch function to wrap (typically globalThis.fetch)\n * @param walletClient - The wallet client used to sign payment messages\n * @param maxValue - The maximum allowed payment amount in base units (defaults to 0.1 USDC)\n * @param paymentRequirementsSelector - A function that selects the payment requirements from the response\n * @param config - Optional configuration for X402 operations (e.g., custom RPC URLs)\n * @returns A wrapped fetch function that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * const wallet = new SignerWallet(...);\n * const fetchWithPay = wrapFetchWithPayment(fetch, wallet);\n *\n * // With custom RPC configuration\n * const fetchWithPay = wrapFetchWithPayment(fetch, wallet, undefined, undefined, {\n *   svmConfig: { rpcUrl: \"http://localhost:8899\" }\n * });\n *\n * // Make a request that may require payment\n * const response = await fetchWithPay('https://api.example.com/paid-endpoint');\n * ```\n *\n * @throws {Error} If the payment amount exceeds the maximum allowed value\n * @throws {Error} If the request configuration is missing\n * @throws {Error} If a payment has already been attempted for this request\n * @throws {Error} If there's an error creating the payment header\n */\nexport function wrapFetchWithPayment(\n  fetch: typeof globalThis.fetch,\n  walletClient: Signer | MultiNetworkSigner,\n  maxValue: bigint = BigInt(0.1 * 10 ** 6), // Default to 0.10 USDC\n  paymentRequirementsSelector: PaymentRequirementsSelector = selectPaymentRequirements,\n  config?: X402Config,\n) {\n  return async (input: RequestInfo, init?: RequestInit) => {\n    const response = await fetch(input, init);\n\n    if (response.status !== 402) {\n      return response;\n    }\n\n    const { x402Version, accepts } = (await response.json()) as {\n      x402Version: number;\n      accepts: unknown[];\n    };\n    const parsedPaymentRequirements = accepts.map(x => PaymentRequirementsSchema.parse(x));\n\n    const network = isMultiNetworkSigner(walletClient)\n      ? undefined\n      : evm.isSignerWallet(walletClient as typeof evm.EvmSigner)\n        ? ChainIdToNetwork[(walletClient as typeof evm.EvmSigner).chain?.id]\n        : isSvmSignerWallet(walletClient)\n          ? ([\"solana\", \"solana-devnet\"] as Network[])\n          : undefined;\n\n    const selectedPaymentRequirements = paymentRequirementsSelector(\n      parsedPaymentRequirements,\n      network,\n      \"exact\",\n    );\n\n    if (BigInt(selectedPaymentRequirements.maxAmountRequired) > maxValue) {\n      throw new Error(\"Payment amount exceeds maximum allowed\");\n    }\n\n    // 获取支付类型，默认为 eip3009\n    const paymentType = selectedPaymentRequirements.paymentType || \"eip3009\";\n\n    // 根据支付类型创建支付头\n    let paymentHeader: string;\n\n    // 仅对 EVM 网络支持 permit 和 permit2\n    const isEvmNetwork = network && ![\"solana\", \"solana-devnet\"].includes(network[0]);\n\n    if (paymentType === \"permit\" && isEvmNetwork) {\n      // 使用 EIP-2612 Permit\n      if (!evm.isSignerWallet(walletClient as typeof evm.EvmSigner)) {\n        throw new Error(\"Permit authorization requires an EVM signer wallet\");\n      }\n      paymentHeader = await exact.evm.permit.createPaymentHeader(\n        walletClient as typeof evm.EvmSigner,\n        x402Version,\n        selectedPaymentRequirements,\n      );\n    } else if (paymentType === \"permit2\" && isEvmNetwork) {\n      // 使用 Permit2\n      if (!evm.isSignerWallet(walletClient as typeof evm.EvmSigner)) {\n        throw new Error(\"Permit2 authorization requires an EVM signer wallet\");\n      }\n      paymentHeader = await exact.evm.permit2.createPaymentHeader(\n        walletClient as typeof evm.EvmSigner,\n        x402Version,\n        selectedPaymentRequirements,\n      );\n    } else if (paymentType === \"eip3009\" || !paymentType) {\n      // 默认使用 EIP-3009（统一的 createPaymentHeader）\n      paymentHeader = await createPaymentHeader(\n        walletClient,\n        x402Version,\n        selectedPaymentRequirements,\n        config,\n      );\n    } else {\n      throw new Error(`Unsupported payment type: ${paymentType}`);\n    }\n\n    if (!init) {\n      throw new Error(\"Missing fetch request configuration\");\n    }\n\n    if ((init as { __is402Retry?: boolean }).__is402Retry) {\n      throw new Error(\"Payment already attempted\");\n    }\n\n    const newInit = {\n      ...init,\n      headers: {\n        ...(init.headers || {}),\n        \"X-PAYMENT\": paymentHeader,\n        \"Access-Control-Expose-Headers\": \"X-PAYMENT-RESPONSE\",\n      },\n      __is402Retry: true,\n    };\n\n    const secondResponse = await fetch(input, newInit);\n    return secondResponse;\n  };\n}\n\nexport { decodeXPaymentResponse } from \"x402/shared\";\nexport {\n  createSigner,\n  createConnectedClient,\n  withChain,\n  type Signer,\n  type ConnectedClient,\n  type MultiNetworkSigner,\n  type X402Config,\n  type EvmChainConfig\n} from \"x402/types\";\nexport { type PaymentRequirementsSelector } from \"x402/client\";\nexport type { Hex, Chain } from \"viem\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EAEA;AAAA,EAEA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE;AAAA,EAEA;AAAA,OACK;AACP,SAAS,aAAa;AA6ItB,SAAS,8BAA8B;AACvC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AAhHA,SAAS,qBACd,OACA,cACA,WAAmB,OAAO,MAAM,MAAM,CAAC,GACvC,8BAA2D,2BAC3D,QACA;AACA,SAAO,OAAO,OAAoB,SAAuB;AA9D3D;AA+DI,UAAM,WAAW,MAAM,MAAM,OAAO,IAAI;AAExC,QAAI,SAAS,WAAW,KAAK;AAC3B,aAAO;AAAA,IACT;AAEA,UAAM,EAAE,aAAa,QAAQ,IAAK,MAAM,SAAS,KAAK;AAItD,UAAM,4BAA4B,QAAQ,IAAI,OAAK,0BAA0B,MAAM,CAAC,CAAC;AAErF,UAAM,UAAU,qBAAqB,YAAY,IAC7C,SACA,IAAI,eAAe,YAAoC,IACrD,kBAAkB,kBAAsC,UAAtC,mBAA6C,EAAE,IACjE,kBAAkB,YAAY,IAC3B,CAAC,UAAU,eAAe,IAC3B;AAER,UAAM,8BAA8B;AAAA,MAClC;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,QAAI,OAAO,4BAA4B,iBAAiB,IAAI,UAAU;AACpE,YAAM,IAAI,MAAM,wCAAwC;AAAA,IAC1D;AAGA,UAAM,cAAc,4BAA4B,eAAe;AAG/D,QAAI;AAGJ,UAAM,eAAe,WAAW,CAAC,CAAC,UAAU,eAAe,EAAE,SAAS,QAAQ,CAAC,CAAC;AAEhF,QAAI,gBAAgB,YAAY,cAAc;AAE5C,UAAI,CAAC,IAAI,eAAe,YAAoC,GAAG;AAC7D,cAAM,IAAI,MAAM,oDAAoD;AAAA,MACtE;AACA,sBAAgB,MAAM,MAAM,IAAI,OAAO;AAAA,QACrC;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,WAAW,gBAAgB,aAAa,cAAc;AAEpD,UAAI,CAAC,IAAI,eAAe,YAAoC,GAAG;AAC7D,cAAM,IAAI,MAAM,qDAAqD;AAAA,MACvE;AACA,sBAAgB,MAAM,MAAM,IAAI,QAAQ;AAAA,QACtC;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,WAAW,gBAAgB,aAAa,CAAC,aAAa;AAEpD,sBAAgB,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF,OAAO;AACL,YAAM,IAAI,MAAM,6BAA6B,WAAW,EAAE;AAAA,IAC5D;AAEA,QAAI,CAAC,MAAM;AACT,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AAEA,QAAK,KAAoC,cAAc;AACrD,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC7C;AAEA,UAAM,UAAU;AAAA,MACd,GAAG;AAAA,MACH,SAAS;AAAA,QACP,GAAI,KAAK,WAAW,CAAC;AAAA,QACrB,aAAa;AAAA,QACb,iCAAiC;AAAA,MACnC;AAAA,MACA,cAAc;AAAA,IAChB;AAEA,UAAM,iBAAiB,MAAM,MAAM,OAAO,OAAO;AACjD,WAAO;AAAA,EACT;AACF;","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@wtflabs/x402-fetch",
+  "version": "0.0.1-beta.0",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "start": "tsx --env-file=.env index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup",
+    "watch": "tsc --watch",
+    "format": "prettier -c .prettierrc --write \"**/*.{ts,js,cjs,json,md}\"",
+    "format:check": "prettier -c .prettierrc --check \"**/*.{ts,js,cjs,json,md}\"",
+    "lint": "eslint . --ext .ts --fix",
+    "lint:check": "eslint . --ext .ts"
+  },
+  "keywords": [],
+  "license": "Apache-2.0",
+  "author": "Coinbase Inc.",
+  "repository": "https://github.com/coinbase/x402",
+  "description": "x402 Payment Protocol",
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@eslint/js": "^9.24.0",
+    "eslint": "^9.24.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.6",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint-plugin-import": "^2.31.0",
+    "prettier": "3.5.2",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.5",
+    "vite": "^6.2.6"
+  },
+  "dependencies": {
+    "viem": "^2.21.26",
+    "zod": "^3.24.2",
+    "x402": "workspace:^"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.mts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ]
+}