@x402/axios 0.0.1 → 2.1.0

package/README.md

@@ -1 +1,197 @@
-# @x402/axios
+# x402-axios
+
+A utility package that extends Axios to automatically handle 402 Payment Required responses using the x402 payment protocol v2. This package enables seamless integration of payment functionality into your applications when making HTTP requests.
+
+## Installation
+
+```bash
+pnpm install @x402/axios
+```
+
+## Quick Start
+
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create an account
+const account = privateKeyToAccount("0xYourPrivateKey");
+
+// Wrap the axios instance with payment handling
+const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+  schemes: [
+    {
+      network: "eip155:8453", // Base Sepolia
+      client: new ExactEvmScheme(account),
+    },
+  ],
+});
+
+// Make a request that may require payment
+const response = await api.get("https://api.example.com/paid-endpoint");
+
+const data = response.data;
+```
+
+## API
+
+### `wrapAxiosWithPayment(axiosInstance, client)`
+
+Wraps an Axios instance to handle 402 Payment Required responses automatically.
+
+#### Parameters
+
+- `axiosInstance`: The Axios instance to wrap (typically from `axios.create()`)
+- `client`: An x402Client instance with registered payment schemes
+
+### `wrapAxiosWithPaymentFromConfig(axiosInstance, config)`
+
+Convenience wrapper that creates an x402Client from a configuration object.
+
+#### Parameters
+
+- `axiosInstance`: The Axios instance to wrap (typically from `axios.create()`)
+- `config`: Configuration object with the following properties:
+  - `schemes`: Array of scheme registrations, each containing:
+    - `network`: Network identifier (e.g., 'eip155:8453', 'solana:mainnet', 'eip155:*' for wildcards)
+    - `client`: The scheme client implementation (e.g., `ExactEvmScheme`, `ExactSvmScheme`)
+    - `x402Version`: Optional protocol version (defaults to 2, set to 1 for legacy support)
+  - `paymentRequirementsSelector`: Optional function to select payment requirements from multiple options
+
+#### Returns
+
+A wrapped Axios instance that automatically handles 402 responses by:
+1. Making the initial request
+2. If a 402 response is received, parsing the payment requirements
+3. Creating a payment header using the configured scheme client
+4. Retrying the request with the payment header
+
+## Examples
+
+### Basic Usage with EVM
+
+```typescript
+import { config } from "dotenv";
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/axios";
+import { privateKeyToAccount } from "viem/accounts";
+import { ExactEvmScheme } from "@x402/evm";
+
+config();
+
+const { EVM_PRIVATE_KEY, API_URL } = process.env;
+
+const account = privateKeyToAccount(EVM_PRIVATE_KEY as `0x${string}`);
+
+const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+  schemes: [
+    {
+      network: "eip155:*", // Support all EVM chains
+      client: new ExactEvmScheme(account),
+    },
+  ],
+});
+
+// Make a request to a paid API endpoint
+api.get(API_URL)
+  .then(response => {
+    const data = response.data;
+    
+    // Optionally decode the payment response header
+    const paymentResponse = response.headers["payment-response"];
+    if (paymentResponse) {
+      const decoded = decodePaymentResponseHeader(paymentResponse);
+      console.log("Payment details:", decoded);
+    }
+    
+    console.log("Response data:", data);
+  })
+  .catch(error => {
+    console.error(error);
+  });
+```
+
+### Using Builder Pattern
+
+For more control, you can use the builder pattern to register multiple schemes:
+
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPayment, x402Client } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ExactSvmScheme } from "@x402/svm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { createKeyPairSignerFromBytes } from "@solana/kit";
+import { base58 } from "@scure/base";
+
+// Create signers
+const evmSigner = privateKeyToAccount("0xYourPrivateKey");
+const svmSigner = await createKeyPairSignerFromBytes(base58.decode("YourSvmPrivateKey"));
+
+// Build client with multiple schemes
+const client = new x402Client()
+  .register("eip155:*", new ExactEvmScheme(evmSigner))
+  .register("solana:*", new ExactSvmScheme(svmSigner));
+
+// Wrap axios with the client
+const api = wrapAxiosWithPayment(axios.create(), client);
+```
+
+### Multi-Chain Support
+
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm";
+import { ExactSvmScheme } from "@x402/svm";
+
+const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+  schemes: [
+    // EVM chains
+    {
+      network: "eip155:8453", // Base Sepolia
+      client: new ExactEvmScheme(evmAccount),
+    },
+    // SVM chains
+    {
+      network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // Solana devnet
+      client: new ExactSvmScheme(svmSigner),
+    },
+  ],
+});
+```
+
+### Custom Payment Requirements Selector
+
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig, type SelectPaymentRequirements } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm";
+
+// Custom selector that prefers the cheapest option
+const selectCheapestOption: SelectPaymentRequirements = (version, accepts) => {
+  if (!accepts || accepts.length === 0) {
+    throw new Error("No payment options available");
+  }
+  
+  // Sort by value and return the cheapest
+  const sorted = [...accepts].sort((a, b) => 
+    BigInt(a.value) - BigInt(b.value)
+  );
+  
+  return sorted[0];
+};
+
+const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+  schemes: [
+    {
+      network: "eip155:8453",
+      client: new ExactEvmScheme(account),
+    },
+  ],
+  paymentRequirementsSelector: selectCheapestOption,
+});
+```
+

package/dist/cjs/index.d.ts

@@ -0,0 +1,71 @@
+import { x402Client, x402ClientConfig } from '@x402/core/client';
+export { PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+import { AxiosInstance } from 'axios';
+export { decodePaymentResponseHeader } from '@x402/core/http';
+export { Network, PaymentPayload, PaymentRequired, PaymentRequirements, SchemeNetworkClient } from '@x402/core/types';
+
+/**
+ * Wraps an Axios instance with x402 payment handling.
+ *
+ * This function adds an interceptor to automatically handle 402 Payment Required responses
+ * by creating and sending payment headers. It will:
+ * 1. Intercept 402 responses
+ * 2. Parse the payment requirements
+ * 3. Create a payment header using the configured x402HTTPClient
+ * 4. Retry the request with the payment header
+ *
+ * @param axiosInstance - The Axios instance to wrap
+ * @param client - Configured x402Client instance for handling payments
+ * @returns The wrapped Axios instance that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ * import { wrapAxiosWithPayment, x402Client } from '@x402/axios';
+ * import { ExactEvmScheme } from '@x402/evm';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const client = new x402Client()
+ *   .register('eip155:*', new ExactEvmScheme(account));
+ *
+ * const api = wrapAxiosWithPayment(axios.create(), client);
+ *
+ * // Make a request that may require payment
+ * const response = await api.get('https://api.example.com/paid-endpoint');
+ * ```
+ *
+ * @throws {Error} If no schemes are provided
+ * @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 wrapAxiosWithPayment(axiosInstance: AxiosInstance, client: x402Client): AxiosInstance;
+/**
+ * Wraps an Axios instance with x402 payment handling using a configuration object.
+ *
+ * @param axiosInstance - The Axios instance to wrap
+ * @param config - Configuration options including scheme registrations and selectors
+ * @returns The wrapped Axios instance that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ * import { wrapAxiosWithPaymentFromConfig } from '@x402/axios';
+ * import { ExactEvmScheme } from '@x402/evm';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ *
+ * const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+ *   schemes: [
+ *     { network: 'eip155:*', client: new ExactEvmScheme(account) }
+ *   ]
+ * });
+ *
+ * const response = await api.get('https://api.example.com/paid-endpoint');
+ * ```
+ */
+declare function wrapAxiosWithPaymentFromConfig(axiosInstance: AxiosInstance, config: x402ClientConfig): AxiosInstance;
+
+export { wrapAxiosWithPayment, wrapAxiosWithPaymentFromConfig };

package/dist/cjs/index.js

@@ -0,0 +1,105 @@
+"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, {
+  decodePaymentResponseHeader: () => import_http.decodePaymentResponseHeader,
+  wrapAxiosWithPayment: () => wrapAxiosWithPayment,
+  wrapAxiosWithPaymentFromConfig: () => wrapAxiosWithPaymentFromConfig,
+  x402Client: () => import_client2.x402Client,
+  x402HTTPClient: () => import_client2.x402HTTPClient
+});
+module.exports = __toCommonJS(src_exports);
+var import_client = require("@x402/core/client");
+var import_client2 = require("@x402/core/client");
+var import_http = require("@x402/core/http");
+function wrapAxiosWithPayment(axiosInstance, client) {
+  const httpClient = new import_client.x402HTTPClient(client);
+  axiosInstance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (!error.response || error.response.status !== 402) {
+        return Promise.reject(error);
+      }
+      const originalConfig = error.config;
+      if (!originalConfig || !originalConfig.headers) {
+        return Promise.reject(new Error("Missing axios request configuration"));
+      }
+      if (originalConfig.__is402Retry) {
+        return Promise.reject(error);
+      }
+      try {
+        let paymentRequired;
+        try {
+          const response = error.response;
+          const getHeader = (name) => {
+            const value = response.headers[name] ?? response.headers[name.toLowerCase()];
+            return typeof value === "string" ? value : void 0;
+          };
+          const body = response.data;
+          paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);
+        } catch (parseError) {
+          return Promise.reject(
+            new Error(
+              `Failed to parse payment requirements: ${parseError instanceof Error ? parseError.message : "Unknown error"}`
+            )
+          );
+        }
+        let paymentPayload;
+        try {
+          paymentPayload = await client.createPaymentPayload(paymentRequired);
+        } catch (paymentError) {
+          return Promise.reject(
+            new Error(
+              `Failed to create payment payload: ${paymentError instanceof Error ? paymentError.message : "Unknown error"}`
+            )
+          );
+        }
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+        originalConfig.__is402Retry = true;
+        Object.entries(paymentHeaders).forEach(([key, value]) => {
+          originalConfig.headers.set(key, value);
+        });
+        originalConfig.headers.set(
+          "Access-Control-Expose-Headers",
+          "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
+        );
+        const secondResponse = await axiosInstance.request(originalConfig);
+        return secondResponse;
+      } catch (retryError) {
+        return Promise.reject(retryError);
+      }
+    }
+  );
+  return axiosInstance;
+}
+function wrapAxiosWithPaymentFromConfig(axiosInstance, config) {
+  const client = import_client.x402Client.fromConfig(config);
+  return wrapAxiosWithPayment(axiosInstance, client);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  decodePaymentResponseHeader,
+  wrapAxiosWithPayment,
+  wrapAxiosWithPaymentFromConfig,
+  x402Client,
+  x402HTTPClient
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["import { x402Client, x402ClientConfig, x402HTTPClient } from \"@x402/core/client\";\nimport { type PaymentRequired } from \"@x402/core/types\";\nimport type { AxiosInstance, AxiosError, InternalAxiosRequestConfig } from \"axios\";\n\n/**\n * Wraps an Axios instance with x402 payment handling.\n *\n * This function adds an interceptor to automatically handle 402 Payment Required responses\n * by creating and sending payment headers. It will:\n * 1. Intercept 402 responses\n * 2. Parse the payment requirements\n * 3. Create a payment header using the configured x402HTTPClient\n * 4. Retry the request with the payment header\n *\n * @param axiosInstance - The Axios instance to wrap\n * @param client - Configured x402Client instance for handling payments\n * @returns The wrapped Axios instance that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * import axios from 'axios';\n * import { wrapAxiosWithPayment, x402Client } from '@x402/axios';\n * import { ExactEvmScheme } from '@x402/evm';\n * import { privateKeyToAccount } from 'viem/accounts';\n *\n * const account = privateKeyToAccount('0x...');\n * const client = new x402Client()\n *   .register('eip155:*', new ExactEvmScheme(account));\n *\n * const api = wrapAxiosWithPayment(axios.create(), client);\n *\n * // Make a request that may require payment\n * const response = await api.get('https://api.example.com/paid-endpoint');\n * ```\n *\n * @throws {Error} If no schemes are provided\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 wrapAxiosWithPayment(\n  axiosInstance: AxiosInstance,\n  client: x402Client,\n): AxiosInstance {\n  const httpClient = new x402HTTPClient(client);\n\n  axiosInstance.interceptors.response.use(\n    response => response,\n    async (error: AxiosError) => {\n      if (!error.response || error.response.status !== 402) {\n        return Promise.reject(error);\n      }\n\n      const originalConfig = error.config;\n      if (!originalConfig || !originalConfig.headers) {\n        return Promise.reject(new Error(\"Missing axios request configuration\"));\n      }\n\n      // Check if this is already a retry to prevent infinite loops\n      if (\n        (originalConfig as InternalAxiosRequestConfig & { __is402Retry?: boolean }).__is402Retry\n      ) {\n        return Promise.reject(error);\n      }\n\n      try {\n        // Parse payment requirements from response\n        let paymentRequired: PaymentRequired;\n        try {\n          const response = error.response!; // Already validated above\n\n          // Create getHeader function for case-insensitive header lookup\n          const getHeader = (name: string) => {\n            const value = response.headers[name] ?? response.headers[name.toLowerCase()];\n            return typeof value === \"string\" ? value : undefined;\n          };\n\n          // Try to get from headers first (v2), then from body (v1)\n          const body = response.data as PaymentRequired | undefined;\n\n          paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);\n        } catch (parseError) {\n          return Promise.reject(\n            new Error(\n              `Failed to parse payment requirements: ${parseError instanceof Error ? parseError.message : \"Unknown error\"}`,\n            ),\n          );\n        }\n\n        // Create payment payload\n        let paymentPayload;\n        try {\n          paymentPayload = await client.createPaymentPayload(paymentRequired);\n        } catch (paymentError) {\n          return Promise.reject(\n            new Error(\n              `Failed to create payment payload: ${paymentError instanceof Error ? paymentError.message : \"Unknown error\"}`,\n            ),\n          );\n        }\n\n        // Encode payment header\n        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);\n\n        // Mark this as a retry\n        (originalConfig as InternalAxiosRequestConfig & { __is402Retry?: boolean }).__is402Retry =\n          true;\n\n        // Add payment headers to the request\n        Object.entries(paymentHeaders).forEach(([key, value]) => {\n          originalConfig.headers.set(key, value);\n        });\n\n        // Add CORS header to expose payment response\n        originalConfig.headers.set(\n          \"Access-Control-Expose-Headers\",\n          \"PAYMENT-RESPONSE,X-PAYMENT-RESPONSE\",\n        );\n\n        // Retry the request with payment\n        const secondResponse = await axiosInstance.request(originalConfig);\n        return secondResponse;\n      } catch (retryError) {\n        return Promise.reject(retryError);\n      }\n    },\n  );\n\n  return axiosInstance;\n}\n\n/**\n * Wraps an Axios instance with x402 payment handling using a configuration object.\n *\n * @param axiosInstance - The Axios instance to wrap\n * @param config - Configuration options including scheme registrations and selectors\n * @returns The wrapped Axios instance that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * import axios from 'axios';\n * import { wrapAxiosWithPaymentFromConfig } from '@x402/axios';\n * import { ExactEvmScheme } from '@x402/evm';\n * import { privateKeyToAccount } from 'viem/accounts';\n *\n * const account = privateKeyToAccount('0x...');\n *\n * const api = wrapAxiosWithPaymentFromConfig(axios.create(), {\n *   schemes: [\n *     { network: 'eip155:*', client: new ExactEvmScheme(account) }\n *   ]\n * });\n *\n * const response = await api.get('https://api.example.com/paid-endpoint');\n * ```\n */\nexport function wrapAxiosWithPaymentFromConfig(\n  axiosInstance: AxiosInstance,\n  config: x402ClientConfig,\n): AxiosInstance {\n  const client = x402Client.fromConfig(config);\n  return wrapAxiosWithPayment(axiosInstance, client);\n}\n\n// Re-export types and utilities for convenience\nexport { x402Client, x402HTTPClient } from \"@x402/core/client\";\nexport type {\n  PaymentPolicy,\n  SchemeRegistration,\n  SelectPaymentRequirements,\n  x402ClientConfig,\n} from \"@x402/core/client\";\nexport { decodePaymentResponseHeader } from \"@x402/core/http\";\nexport type {\n  Network,\n  PaymentPayload,\n  PaymentRequired,\n  PaymentRequirements,\n  SchemeNetworkClient,\n} from \"@x402/core/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAA6D;AAqK7D,IAAAA,iBAA2C;AAO3C,kBAA4C;AApIrC,SAAS,qBACd,eACA,QACe;AACf,QAAM,aAAa,IAAI,6BAAe,MAAM;AAE5C,gBAAc,aAAa,SAAS;AAAA,IAClC,cAAY;AAAA,IACZ,OAAO,UAAsB;AAC3B,UAAI,CAAC,MAAM,YAAY,MAAM,SAAS,WAAW,KAAK;AACpD,eAAO,QAAQ,OAAO,KAAK;AAAA,MAC7B;AAEA,YAAM,iBAAiB,MAAM;AAC7B,UAAI,CAAC,kBAAkB,CAAC,eAAe,SAAS;AAC9C,eAAO,QAAQ,OAAO,IAAI,MAAM,qCAAqC,CAAC;AAAA,MACxE;AAGA,UACG,eAA2E,cAC5E;AACA,eAAO,QAAQ,OAAO,KAAK;AAAA,MAC7B;AAEA,UAAI;AAEF,YAAI;AACJ,YAAI;AACF,gBAAM,WAAW,MAAM;AAGvB,gBAAM,YAAY,CAAC,SAAiB;AAClC,kBAAM,QAAQ,SAAS,QAAQ,IAAI,KAAK,SAAS,QAAQ,KAAK,YAAY,CAAC;AAC3E,mBAAO,OAAO,UAAU,WAAW,QAAQ;AAAA,UAC7C;AAGA,gBAAM,OAAO,SAAS;AAEtB,4BAAkB,WAAW,2BAA2B,WAAW,IAAI;AAAA,QACzE,SAAS,YAAY;AACnB,iBAAO,QAAQ;AAAA,YACb,IAAI;AAAA,cACF,yCAAyC,sBAAsB,QAAQ,WAAW,UAAU,eAAe;AAAA,YAC7G;AAAA,UACF;AAAA,QACF;AAGA,YAAI;AACJ,YAAI;AACF,2BAAiB,MAAM,OAAO,qBAAqB,eAAe;AAAA,QACpE,SAAS,cAAc;AACrB,iBAAO,QAAQ;AAAA,YACb,IAAI;AAAA,cACF,qCAAqC,wBAAwB,QAAQ,aAAa,UAAU,eAAe;AAAA,YAC7G;AAAA,UACF;AAAA,QACF;AAGA,cAAM,iBAAiB,WAAW,6BAA6B,cAAc;AAG7E,QAAC,eAA2E,eAC1E;AAGF,eAAO,QAAQ,cAAc,EAAE,QAAQ,CAAC,CAAC,KAAK,KAAK,MAAM;AACvD,yBAAe,QAAQ,IAAI,KAAK,KAAK;AAAA,QACvC,CAAC;AAGD,uBAAe,QAAQ;AAAA,UACrB;AAAA,UACA;AAAA,QACF;AAGA,cAAM,iBAAiB,MAAM,cAAc,QAAQ,cAAc;AACjE,eAAO;AAAA,MACT,SAAS,YAAY;AACnB,eAAO,QAAQ,OAAO,UAAU;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AA2BO,SAAS,+BACd,eACA,QACe;AACf,QAAM,SAAS,yBAAW,WAAW,MAAM;AAC3C,SAAO,qBAAqB,eAAe,MAAM;AACnD;","names":["import_client"]}

package/dist/esm/index.d.mts

@@ -0,0 +1,71 @@
+import { x402Client, x402ClientConfig } from '@x402/core/client';
+export { PaymentPolicy, SchemeRegistration, SelectPaymentRequirements, x402Client, x402ClientConfig, x402HTTPClient } from '@x402/core/client';
+import { AxiosInstance } from 'axios';
+export { decodePaymentResponseHeader } from '@x402/core/http';
+export { Network, PaymentPayload, PaymentRequired, PaymentRequirements, SchemeNetworkClient } from '@x402/core/types';
+
+/**
+ * Wraps an Axios instance with x402 payment handling.
+ *
+ * This function adds an interceptor to automatically handle 402 Payment Required responses
+ * by creating and sending payment headers. It will:
+ * 1. Intercept 402 responses
+ * 2. Parse the payment requirements
+ * 3. Create a payment header using the configured x402HTTPClient
+ * 4. Retry the request with the payment header
+ *
+ * @param axiosInstance - The Axios instance to wrap
+ * @param client - Configured x402Client instance for handling payments
+ * @returns The wrapped Axios instance that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ * import { wrapAxiosWithPayment, x402Client } from '@x402/axios';
+ * import { ExactEvmScheme } from '@x402/evm';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const client = new x402Client()
+ *   .register('eip155:*', new ExactEvmScheme(account));
+ *
+ * const api = wrapAxiosWithPayment(axios.create(), client);
+ *
+ * // Make a request that may require payment
+ * const response = await api.get('https://api.example.com/paid-endpoint');
+ * ```
+ *
+ * @throws {Error} If no schemes are provided
+ * @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 wrapAxiosWithPayment(axiosInstance: AxiosInstance, client: x402Client): AxiosInstance;
+/**
+ * Wraps an Axios instance with x402 payment handling using a configuration object.
+ *
+ * @param axiosInstance - The Axios instance to wrap
+ * @param config - Configuration options including scheme registrations and selectors
+ * @returns The wrapped Axios instance that handles 402 responses automatically
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ * import { wrapAxiosWithPaymentFromConfig } from '@x402/axios';
+ * import { ExactEvmScheme } from '@x402/evm';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ *
+ * const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+ *   schemes: [
+ *     { network: 'eip155:*', client: new ExactEvmScheme(account) }
+ *   ]
+ * });
+ *
+ * const response = await api.get('https://api.example.com/paid-endpoint');
+ * ```
+ */
+declare function wrapAxiosWithPaymentFromConfig(axiosInstance: AxiosInstance, config: x402ClientConfig): AxiosInstance;
+
+export { wrapAxiosWithPayment, wrapAxiosWithPaymentFromConfig };

package/dist/esm/index.mjs

@@ -0,0 +1,76 @@
+// src/index.ts
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { x402Client as x402Client2, x402HTTPClient as x402HTTPClient2 } from "@x402/core/client";
+import { decodePaymentResponseHeader } from "@x402/core/http";
+function wrapAxiosWithPayment(axiosInstance, client) {
+  const httpClient = new x402HTTPClient(client);
+  axiosInstance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (!error.response || error.response.status !== 402) {
+        return Promise.reject(error);
+      }
+      const originalConfig = error.config;
+      if (!originalConfig || !originalConfig.headers) {
+        return Promise.reject(new Error("Missing axios request configuration"));
+      }
+      if (originalConfig.__is402Retry) {
+        return Promise.reject(error);
+      }
+      try {
+        let paymentRequired;
+        try {
+          const response = error.response;
+          const getHeader = (name) => {
+            const value = response.headers[name] ?? response.headers[name.toLowerCase()];
+            return typeof value === "string" ? value : void 0;
+          };
+          const body = response.data;
+          paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);
+        } catch (parseError) {
+          return Promise.reject(
+            new Error(
+              `Failed to parse payment requirements: ${parseError instanceof Error ? parseError.message : "Unknown error"}`
+            )
+          );
+        }
+        let paymentPayload;
+        try {
+          paymentPayload = await client.createPaymentPayload(paymentRequired);
+        } catch (paymentError) {
+          return Promise.reject(
+            new Error(
+              `Failed to create payment payload: ${paymentError instanceof Error ? paymentError.message : "Unknown error"}`
+            )
+          );
+        }
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+        originalConfig.__is402Retry = true;
+        Object.entries(paymentHeaders).forEach(([key, value]) => {
+          originalConfig.headers.set(key, value);
+        });
+        originalConfig.headers.set(
+          "Access-Control-Expose-Headers",
+          "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
+        );
+        const secondResponse = await axiosInstance.request(originalConfig);
+        return secondResponse;
+      } catch (retryError) {
+        return Promise.reject(retryError);
+      }
+    }
+  );
+  return axiosInstance;
+}
+function wrapAxiosWithPaymentFromConfig(axiosInstance, config) {
+  const client = x402Client.fromConfig(config);
+  return wrapAxiosWithPayment(axiosInstance, client);
+}
+export {
+  decodePaymentResponseHeader,
+  wrapAxiosWithPayment,
+  wrapAxiosWithPaymentFromConfig,
+  x402Client2 as x402Client,
+  x402HTTPClient2 as x402HTTPClient
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["import { x402Client, x402ClientConfig, x402HTTPClient } from \"@x402/core/client\";\nimport { type PaymentRequired } from \"@x402/core/types\";\nimport type { AxiosInstance, AxiosError, InternalAxiosRequestConfig } from \"axios\";\n\n/**\n * Wraps an Axios instance with x402 payment handling.\n *\n * This function adds an interceptor to automatically handle 402 Payment Required responses\n * by creating and sending payment headers. It will:\n * 1. Intercept 402 responses\n * 2. Parse the payment requirements\n * 3. Create a payment header using the configured x402HTTPClient\n * 4. Retry the request with the payment header\n *\n * @param axiosInstance - The Axios instance to wrap\n * @param client - Configured x402Client instance for handling payments\n * @returns The wrapped Axios instance that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * import axios from 'axios';\n * import { wrapAxiosWithPayment, x402Client } from '@x402/axios';\n * import { ExactEvmScheme } from '@x402/evm';\n * import { privateKeyToAccount } from 'viem/accounts';\n *\n * const account = privateKeyToAccount('0x...');\n * const client = new x402Client()\n *   .register('eip155:*', new ExactEvmScheme(account));\n *\n * const api = wrapAxiosWithPayment(axios.create(), client);\n *\n * // Make a request that may require payment\n * const response = await api.get('https://api.example.com/paid-endpoint');\n * ```\n *\n * @throws {Error} If no schemes are provided\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 wrapAxiosWithPayment(\n  axiosInstance: AxiosInstance,\n  client: x402Client,\n): AxiosInstance {\n  const httpClient = new x402HTTPClient(client);\n\n  axiosInstance.interceptors.response.use(\n    response => response,\n    async (error: AxiosError) => {\n      if (!error.response || error.response.status !== 402) {\n        return Promise.reject(error);\n      }\n\n      const originalConfig = error.config;\n      if (!originalConfig || !originalConfig.headers) {\n        return Promise.reject(new Error(\"Missing axios request configuration\"));\n      }\n\n      // Check if this is already a retry to prevent infinite loops\n      if (\n        (originalConfig as InternalAxiosRequestConfig & { __is402Retry?: boolean }).__is402Retry\n      ) {\n        return Promise.reject(error);\n      }\n\n      try {\n        // Parse payment requirements from response\n        let paymentRequired: PaymentRequired;\n        try {\n          const response = error.response!; // Already validated above\n\n          // Create getHeader function for case-insensitive header lookup\n          const getHeader = (name: string) => {\n            const value = response.headers[name] ?? response.headers[name.toLowerCase()];\n            return typeof value === \"string\" ? value : undefined;\n          };\n\n          // Try to get from headers first (v2), then from body (v1)\n          const body = response.data as PaymentRequired | undefined;\n\n          paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);\n        } catch (parseError) {\n          return Promise.reject(\n            new Error(\n              `Failed to parse payment requirements: ${parseError instanceof Error ? parseError.message : \"Unknown error\"}`,\n            ),\n          );\n        }\n\n        // Create payment payload\n        let paymentPayload;\n        try {\n          paymentPayload = await client.createPaymentPayload(paymentRequired);\n        } catch (paymentError) {\n          return Promise.reject(\n            new Error(\n              `Failed to create payment payload: ${paymentError instanceof Error ? paymentError.message : \"Unknown error\"}`,\n            ),\n          );\n        }\n\n        // Encode payment header\n        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);\n\n        // Mark this as a retry\n        (originalConfig as InternalAxiosRequestConfig & { __is402Retry?: boolean }).__is402Retry =\n          true;\n\n        // Add payment headers to the request\n        Object.entries(paymentHeaders).forEach(([key, value]) => {\n          originalConfig.headers.set(key, value);\n        });\n\n        // Add CORS header to expose payment response\n        originalConfig.headers.set(\n          \"Access-Control-Expose-Headers\",\n          \"PAYMENT-RESPONSE,X-PAYMENT-RESPONSE\",\n        );\n\n        // Retry the request with payment\n        const secondResponse = await axiosInstance.request(originalConfig);\n        return secondResponse;\n      } catch (retryError) {\n        return Promise.reject(retryError);\n      }\n    },\n  );\n\n  return axiosInstance;\n}\n\n/**\n * Wraps an Axios instance with x402 payment handling using a configuration object.\n *\n * @param axiosInstance - The Axios instance to wrap\n * @param config - Configuration options including scheme registrations and selectors\n * @returns The wrapped Axios instance that handles 402 responses automatically\n *\n * @example\n * ```typescript\n * import axios from 'axios';\n * import { wrapAxiosWithPaymentFromConfig } from '@x402/axios';\n * import { ExactEvmScheme } from '@x402/evm';\n * import { privateKeyToAccount } from 'viem/accounts';\n *\n * const account = privateKeyToAccount('0x...');\n *\n * const api = wrapAxiosWithPaymentFromConfig(axios.create(), {\n *   schemes: [\n *     { network: 'eip155:*', client: new ExactEvmScheme(account) }\n *   ]\n * });\n *\n * const response = await api.get('https://api.example.com/paid-endpoint');\n * ```\n */\nexport function wrapAxiosWithPaymentFromConfig(\n  axiosInstance: AxiosInstance,\n  config: x402ClientConfig,\n): AxiosInstance {\n  const client = x402Client.fromConfig(config);\n  return wrapAxiosWithPayment(axiosInstance, client);\n}\n\n// Re-export types and utilities for convenience\nexport { x402Client, x402HTTPClient } from \"@x402/core/client\";\nexport type {\n  PaymentPolicy,\n  SchemeRegistration,\n  SelectPaymentRequirements,\n  x402ClientConfig,\n} from \"@x402/core/client\";\nexport { decodePaymentResponseHeader } from \"@x402/core/http\";\nexport type {\n  Network,\n  PaymentPayload,\n  PaymentRequired,\n  PaymentRequirements,\n  SchemeNetworkClient,\n} from \"@x402/core/types\";\n"],"mappings":";AAAA,SAAS,YAA8B,sBAAsB;AAqK7D,SAAS,cAAAA,aAAY,kBAAAC,uBAAsB;AAO3C,SAAS,mCAAmC;AApIrC,SAAS,qBACd,eACA,QACe;AACf,QAAM,aAAa,IAAI,eAAe,MAAM;AAE5C,gBAAc,aAAa,SAAS;AAAA,IAClC,cAAY;AAAA,IACZ,OAAO,UAAsB;AAC3B,UAAI,CAAC,MAAM,YAAY,MAAM,SAAS,WAAW,KAAK;AACpD,eAAO,QAAQ,OAAO,KAAK;AAAA,MAC7B;AAEA,YAAM,iBAAiB,MAAM;AAC7B,UAAI,CAAC,kBAAkB,CAAC,eAAe,SAAS;AAC9C,eAAO,QAAQ,OAAO,IAAI,MAAM,qCAAqC,CAAC;AAAA,MACxE;AAGA,UACG,eAA2E,cAC5E;AACA,eAAO,QAAQ,OAAO,KAAK;AAAA,MAC7B;AAEA,UAAI;AAEF,YAAI;AACJ,YAAI;AACF,gBAAM,WAAW,MAAM;AAGvB,gBAAM,YAAY,CAAC,SAAiB;AAClC,kBAAM,QAAQ,SAAS,QAAQ,IAAI,KAAK,SAAS,QAAQ,KAAK,YAAY,CAAC;AAC3E,mBAAO,OAAO,UAAU,WAAW,QAAQ;AAAA,UAC7C;AAGA,gBAAM,OAAO,SAAS;AAEtB,4BAAkB,WAAW,2BAA2B,WAAW,IAAI;AAAA,QACzE,SAAS,YAAY;AACnB,iBAAO,QAAQ;AAAA,YACb,IAAI;AAAA,cACF,yCAAyC,sBAAsB,QAAQ,WAAW,UAAU,eAAe;AAAA,YAC7G;AAAA,UACF;AAAA,QACF;AAGA,YAAI;AACJ,YAAI;AACF,2BAAiB,MAAM,OAAO,qBAAqB,eAAe;AAAA,QACpE,SAAS,cAAc;AACrB,iBAAO,QAAQ;AAAA,YACb,IAAI;AAAA,cACF,qCAAqC,wBAAwB,QAAQ,aAAa,UAAU,eAAe;AAAA,YAC7G;AAAA,UACF;AAAA,QACF;AAGA,cAAM,iBAAiB,WAAW,6BAA6B,cAAc;AAG7E,QAAC,eAA2E,eAC1E;AAGF,eAAO,QAAQ,cAAc,EAAE,QAAQ,CAAC,CAAC,KAAK,KAAK,MAAM;AACvD,yBAAe,QAAQ,IAAI,KAAK,KAAK;AAAA,QACvC,CAAC;AAGD,uBAAe,QAAQ;AAAA,UACrB;AAAA,UACA;AAAA,QACF;AAGA,cAAM,iBAAiB,MAAM,cAAc,QAAQ,cAAc;AACjE,eAAO;AAAA,MACT,SAAS,YAAY;AACnB,eAAO,QAAQ,OAAO,UAAU;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AA2BO,SAAS,+BACd,eACA,QACe;AACf,QAAM,SAAS,WAAW,WAAW,MAAM;AAC3C,SAAO,qBAAqB,eAAe,MAAM;AACnD;","names":["x402Client","x402HTTPClient"]}

package/package.json

@@ -1,12 +1,60 @@
 {
   "name": "@x402/axios",
-  "version": "0.0.1",
-  "description": "The Axios interceptor package for the x402 payment protocol",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "Coinbase Inc.",
+  "version": "2.1.0",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "keywords": [],
   "license": "Apache-2.0",
-  "repository": "https://github.com/coinbase/x402"
+  "author": "Coinbase Inc.",
+  "repository": "https://github.com/coinbase/x402",
+  "description": "x402 Payment Protocol",
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.6",
+    "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": {
+    "axios": "^1.7.9",
+    "zod": "^3.24.2",
+    "@x402/core": "^2.1.0"
+  },
+  "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"
+  ],
+  "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"
+  }
 }

package/index.js

@@ -1,3 +0,0 @@
-// Placeholder for @x402/axios
-module.exports = {};
-