@axonfi/sdk 0.3.7 → 0.4.1

package/README.md

@@ -14,7 +14,7 @@ Giving bots funded wallets is risky: scattered keys, no spending controls, one c
 - **Bounded risk** — per-tx caps, daily limits, velocity windows, destination whitelists. Bots can only operate within the policies you set.
 - **AI verification** — 3-agent LLM consensus (safety, behavioral, reasoning) for flagged transactions. 2/3 consensus required.
 - **Gasless bots** — bots sign EIP-712 intents off-chain. Axon's relayer handles gas, simulation, and on-chain execution.
-- **Multi-chain** — Base, Arbitrum, Optimism, Polygon. USDC as base asset.
+- **Multi-chain** — Base, Arbitrum. USDC as base asset.
 
 Your agents pay. You stay in control.
 
@@ -185,6 +185,28 @@ Payments resolve through one of three paths:
 | **AI Scan**      | Exceeds AI threshold | ~30s   | `status: "approved"` or routes to review    |
 | **Human Review** | No AI consensus      | Async  | `status: "pending_review"`, poll for result |
 
+## HTTP 402 Paywalls (x402)
+
+The SDK handles [x402](https://www.x402.org/) paywalls — APIs that charge per-request via HTTP 402 Payment Required. When a bot hits a paywall, the SDK parses the payment requirements, funds the bot from the vault, signs a token authorization, and returns a header for the retry.
+
+```typescript
+const response = await fetch('https://api.example.com/data');
+
+if (response.status === 402) {
+  // SDK handles everything: parse header, fund bot from vault, sign authorization
+  const result = await axon.x402.handlePaymentRequired(response.headers);
+
+  // Retry with the payment signature
+  const data = await fetch('https://api.example.com/data', {
+    headers: { 'PAYMENT-SIGNATURE': result.paymentSignature },
+  });
+}
+```
+
+The full pipeline applies — spending limits, AI verification, human review — even for 402 payments. Vault owners see every paywall payment in the dashboard with the resource URL, merchant address, and amount.
+
+Supports EIP-3009 (USDC, gasless) and Permit2 (any ERC-20) settlement schemes.
+
 ## Security Model
 
 - **Owners** control everything: bot whitelist, spending limits, withdrawal. Hardware wallet recommended.
@@ -199,8 +221,7 @@ Payments resolve through one of three paths:
 | Base Sepolia | 84532 | Live        |
 | Base         | 8453  | Coming soon |
 | Arbitrum One | 42161 | Coming soon |
-| Optimism     | 10    | Coming soon |
-| Polygon PoS  | 137   | Coming soon |
+| Arbitrum Sepolia | 421614 | Live |
 
 ## Links
 

package/dist/index.cjs

@@ -3032,14 +3032,371 @@ function generateUuid() {
   const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
+
+// src/x402.ts
+function parsePaymentRequired(headerValue) {
+  let decoded;
+  try {
+    decoded = atob(headerValue);
+  } catch {
+    decoded = headerValue;
+  }
+  const parsed = JSON.parse(decoded);
+  if (!parsed.accepts || !Array.isArray(parsed.accepts) || parsed.accepts.length === 0) {
+    throw new Error("x402: no payment options in PAYMENT-REQUIRED header");
+  }
+  if (!parsed.resource) {
+    throw new Error("x402: missing resource in PAYMENT-REQUIRED header");
+  }
+  return parsed;
+}
+function parseChainId(network) {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "eip155") {
+    throw new Error(`x402: unsupported network format "${network}" (expected "eip155:<chainId>")`);
+  }
+  const chainId = parseInt(parts[1], 10);
+  if (isNaN(chainId)) {
+    throw new Error(`x402: invalid chain ID in network "${network}"`);
+  }
+  return chainId;
+}
+function findMatchingOption(accepts, chainId) {
+  const matchingOptions = [];
+  for (const option of accepts) {
+    try {
+      const optionChainId = parseChainId(option.network);
+      if (optionChainId === chainId) {
+        matchingOptions.push(option);
+      }
+    } catch {
+      continue;
+    }
+  }
+  if (matchingOptions.length === 0) return null;
+  const usdcAddress = USDC[chainId]?.toLowerCase();
+  if (usdcAddress) {
+    const usdcOption = matchingOptions.find((opt) => opt.asset.toLowerCase() === usdcAddress);
+    if (usdcOption) return usdcOption;
+  }
+  return matchingOptions[0] ?? null;
+}
+function extractX402Metadata(parsed, selectedOption) {
+  const metadata = {};
+  if (parsed.x402Version !== void 0) {
+    metadata.x402_version = String(parsed.x402Version);
+  }
+  if (selectedOption.scheme) {
+    metadata.x402_scheme = selectedOption.scheme;
+  }
+  if (parsed.resource.mimeType) {
+    metadata.x402_mime_type = parsed.resource.mimeType;
+  }
+  if (selectedOption.payTo) {
+    metadata.x402_merchant = selectedOption.payTo;
+  }
+  if (parsed.resource.description) {
+    metadata.x402_resource_description = parsed.resource.description;
+  }
+  return {
+    resourceUrl: parsed.resource.url,
+    memo: parsed.resource.description ?? null,
+    recipientLabel: selectedOption.payTo ? `${selectedOption.payTo.slice(0, 6)}...${selectedOption.payTo.slice(-4)}` : null,
+    metadata
+  };
+}
+function formatPaymentSignature(payload) {
+  const json = JSON.stringify(payload);
+  return btoa(json);
+}
+var USDC_EIP712_DOMAIN = {
+  // Base mainnet
+  8453: { name: "USD Coin", version: "2" },
+  // Base Sepolia
+  84532: { name: "USDC", version: "2" },
+  // Arbitrum One
+  42161: { name: "USD Coin", version: "2" },
+  // Arbitrum Sepolia (same as mainnet convention)
+  421614: { name: "USDC", version: "2" }
+};
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function randomNonce() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+async function signTransferWithAuthorization(privateKey, chainId, auth) {
+  const domainConfig = USDC_EIP712_DOMAIN[chainId];
+  if (!domainConfig) {
+    throw new Error(`EIP-3009 not configured for chain ${chainId}`);
+  }
+  const usdcAddress = USDC[chainId];
+  if (!usdcAddress) {
+    throw new Error(`USDC address not known for chain ${chainId}`);
+  }
+  const account = accounts.privateKeyToAccount(privateKey);
+  return account.signTypedData({
+    domain: {
+      name: domainConfig.name,
+      version: domainConfig.version,
+      chainId,
+      verifyingContract: usdcAddress
+    },
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: auth.from,
+      to: auth.to,
+      value: auth.value,
+      validAfter: auth.validAfter,
+      validBefore: auth.validBefore,
+      nonce: auth.nonce
+    }
+  });
+}
+var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+var X402_PROXY_ADDRESS = "0x4020CD856C882D5fb903D99CE35316A085Bb0001";
+var WITNESS_TYPE_STRING = "TransferDetails witness)TokenPermissions(address token,uint256 amount)TransferDetails(address to,uint256 requestedAmount)";
+var PERMIT_WITNESS_TRANSFER_FROM_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "TransferDetails" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ],
+  TransferDetails: [
+    { name: "to", type: "address" },
+    { name: "requestedAmount", type: "uint256" }
+  ]
+};
+function randomPermit2Nonce() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  let n = 0n;
+  for (const b of bytes) {
+    n = n << 8n | BigInt(b);
+  }
+  return n;
+}
+async function signPermit2WitnessTransfer(privateKey, chainId, permit) {
+  const account = accounts.privateKeyToAccount(privateKey);
+  return account.signTypedData({
+    domain: {
+      name: "Permit2",
+      chainId,
+      verifyingContract: PERMIT2_ADDRESS
+    },
+    types: PERMIT_WITNESS_TRANSFER_FROM_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: {
+        token: permit.token,
+        amount: permit.amount
+      },
+      spender: permit.spender,
+      nonce: permit.nonce,
+      deadline: permit.deadline,
+      witness: {
+        to: permit.witnessTo,
+        requestedAmount: permit.witnessRequestedAmount
+      }
+    }
+  });
+}
+
+// src/client.ts
 var AxonClient = class {
   constructor(config) {
+    // ============================================================================
+    // x402 — HTTP 402 Payment Required
+    // ============================================================================
+    /**
+     * x402 utilities for handling HTTP 402 Payment Required responses.
+     *
+     * The x402 flow:
+     * 1. Bot hits an API that returns HTTP 402 + PAYMENT-REQUIRED header
+     * 2. SDK parses the header, finds a matching payment option
+     * 3. SDK funds the bot's EOA from the vault (full Axon pipeline applies)
+     * 4. Bot signs an EIP-3009 or Permit2 authorization
+     * 5. SDK returns a PAYMENT-SIGNATURE header for the bot to retry with
+     *
+     * @example
+     * ```ts
+     * const response = await fetch('https://api.example.com/data');
+     * if (response.status === 402) {
+     *   const result = await client.x402.handlePaymentRequired(response.headers);
+     *   const data = await fetch('https://api.example.com/data', {
+     *     headers: { 'PAYMENT-SIGNATURE': result.paymentSignature },
+     *   });
+     * }
+     * ```
+     */
+    this.x402 = {
+      /**
+       * Fund the bot's EOA from the vault for x402 settlement.
+       *
+       * This is a regular Axon payment (to = bot's own address) that goes through
+       * the full pipeline: policy engine, AI scan, human review if needed.
+       *
+       * @param amount - Amount in token base units
+       * @param token - Token address (defaults to USDC on this chain)
+       * @param metadata - Optional metadata for the payment record
+       */
+      fund: async (amount, token, metadata) => {
+        const tokenAddress = token ?? USDC[this.chainId];
+        if (!tokenAddress) {
+          throw new Error(`No default USDC address for chain ${this.chainId}`);
+        }
+        return this.pay({
+          to: this.botAddress,
+          token: tokenAddress,
+          amount,
+          x402Funding: true,
+          ...metadata
+        });
+      },
+      /**
+       * Handle a full x402 flow: parse header, fund bot, sign authorization, return header.
+       *
+       * Supports both EIP-3009 (USDC) and Permit2 (any ERC-20) settlement.
+       * The bot's EOA is funded from the vault first (full Axon pipeline applies).
+       *
+       * @param headers - Response headers from the 402 response (must contain PAYMENT-REQUIRED)
+       * @param maxTimeoutMs - Maximum time to wait for pending_review resolution (default: 120s)
+       * @param pollIntervalMs - Polling interval for pending_review (default: 5s)
+       * @returns Payment signature header value + funding details
+       */
+      handlePaymentRequired: async (headers, maxTimeoutMs = 12e4, pollIntervalMs = 5e3) => {
+        const headerValue = headers instanceof Headers ? headers.get("payment-required") ?? headers.get("PAYMENT-REQUIRED") : headers["payment-required"] ?? headers["PAYMENT-REQUIRED"];
+        if (!headerValue) {
+          throw new Error("x402: no PAYMENT-REQUIRED header found");
+        }
+        const parsed = parsePaymentRequired(headerValue);
+        const option = findMatchingOption(parsed.accepts, this.chainId);
+        if (!option) {
+          throw new Error(
+            `x402: no payment option matches chain ${this.chainId}. Available: ${parsed.accepts.map((a) => a.network).join(", ")}`
+          );
+        }
+        const x402Meta = extractX402Metadata(parsed, option);
+        const amount = BigInt(option.amount);
+        const tokenAddress = option.asset;
+        const payInput = {
+          to: this.botAddress,
+          token: tokenAddress,
+          amount,
+          x402Funding: true,
+          resourceUrl: x402Meta.resourceUrl,
+          metadata: x402Meta.metadata
+        };
+        if (x402Meta.memo) payInput.memo = x402Meta.memo;
+        if (x402Meta.recipientLabel) payInput.recipientLabel = x402Meta.recipientLabel;
+        let fundingResult = await this.pay(payInput);
+        if (fundingResult.status === "pending_review") {
+          const deadline = Date.now() + maxTimeoutMs;
+          while (fundingResult.status === "pending_review" && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            fundingResult = await this.poll(fundingResult.requestId);
+          }
+          if (fundingResult.status === "pending_review") {
+            throw new Error(`x402: funding timed out after ${maxTimeoutMs}ms (still pending_review)`);
+          }
+        }
+        if (fundingResult.status === "rejected") {
+          throw new Error(`x402: funding rejected \u2014 ${fundingResult.reason ?? "unknown reason"}`);
+        }
+        const botPrivateKey = this.botPrivateKey;
+        const payTo = option.payTo;
+        const usdcAddress = USDC[this.chainId]?.toLowerCase();
+        const isUsdc = tokenAddress.toLowerCase() === usdcAddress;
+        let signaturePayload;
+        if (isUsdc && USDC_EIP712_DOMAIN[this.chainId]) {
+          const nonce = randomNonce();
+          const validAfter = 0n;
+          const validBefore = BigInt(Math.floor(Date.now() / 1e3) + 300);
+          const sig = await signTransferWithAuthorization(botPrivateKey, this.chainId, {
+            from: this.botAddress,
+            to: payTo,
+            value: amount,
+            validAfter,
+            validBefore,
+            nonce
+          });
+          signaturePayload = {
+            scheme: "exact",
+            signature: sig,
+            authorization: {
+              from: this.botAddress,
+              to: payTo,
+              value: amount.toString(),
+              validAfter: validAfter.toString(),
+              validBefore: validBefore.toString(),
+              nonce
+            }
+          };
+        } else {
+          const nonce = randomPermit2Nonce();
+          const deadline = BigInt(Math.floor(Date.now() / 1e3) + 300);
+          const sig = await signPermit2WitnessTransfer(botPrivateKey, this.chainId, {
+            token: tokenAddress,
+            amount,
+            spender: X402_PROXY_ADDRESS,
+            nonce,
+            deadline,
+            witnessTo: payTo,
+            witnessRequestedAmount: amount
+          });
+          signaturePayload = {
+            scheme: "permit2",
+            signature: sig,
+            permit: {
+              permitted: { token: tokenAddress, amount: amount.toString() },
+              spender: X402_PROXY_ADDRESS,
+              nonce: nonce.toString(),
+              deadline: deadline.toString()
+            },
+            witness: {
+              to: payTo,
+              requestedAmount: amount.toString()
+            }
+          };
+        }
+        const paymentSignature = formatPaymentSignature(signaturePayload);
+        const handleResult = {
+          paymentSignature,
+          selectedOption: option,
+          fundingResult: {
+            requestId: fundingResult.requestId,
+            status: fundingResult.status
+          }
+        };
+        if (fundingResult.txHash) {
+          handleResult.fundingResult.txHash = fundingResult.txHash;
+        }
+        return handleResult;
+      }
+    };
     this.vaultAddress = config.vaultAddress;
     this.chainId = config.chainId;
-    this.relayerUrl = "https://relay.axonfi.xyz";
+    this.relayerUrl = config.relayerUrl ?? "https://relay.axonfi.xyz";
     if (!config.botPrivateKey) {
       throw new Error("botPrivateKey is required in AxonClientConfig");
     }
+    this.botPrivateKey = config.botPrivateKey;
     this.walletClient = createAxonWalletClient(config.botPrivateKey, config.chainId);
   }
   // ============================================================================
@@ -3342,7 +3699,8 @@ Timestamp: ${timestamp}`;
       ...input.invoiceId !== void 0 && { invoiceId: input.invoiceId },
       ...input.orderId !== void 0 && { orderId: input.orderId },
       ...input.recipientLabel !== void 0 && { recipientLabel: input.recipientLabel },
-      ...input.metadata !== void 0 && { metadata: input.metadata }
+      ...input.metadata !== void 0 && { metadata: input.metadata },
+      ...input.x402Funding !== void 0 && { x402Funding: input.x402Funding }
     };
     return this._post(RELAYER_API.PAYMENTS, idempotencyKey, body);
   }
@@ -3916,19 +4274,26 @@ exports.EXPLORER_TX = EXPLORER_TX;
 exports.KNOWN_TOKENS = KNOWN_TOKENS;
 exports.NATIVE_ETH = NATIVE_ETH;
 exports.PAYMENT_INTENT_TYPEHASH = PAYMENT_INTENT_TYPEHASH;
+exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS;
 exports.PaymentErrorCode = PaymentErrorCode;
 exports.RELAYER_API = RELAYER_API;
 exports.SUPPORTED_CHAIN_IDS = SUPPORTED_CHAIN_IDS;
 exports.SWAP_INTENT_TYPEHASH = SWAP_INTENT_TYPEHASH;
 exports.Token = Token;
 exports.USDC = USDC;
+exports.USDC_EIP712_DOMAIN = USDC_EIP712_DOMAIN;
 exports.WINDOW = WINDOW;
+exports.WITNESS_TYPE_STRING = WITNESS_TYPE_STRING;
+exports.X402_PROXY_ADDRESS = X402_PROXY_ADDRESS;
 exports.createAxonPublicClient = createAxonPublicClient;
 exports.createAxonWalletClient = createAxonWalletClient;
 exports.decryptKeystore = decryptKeystore;
 exports.deployVault = deployVault;
 exports.encodeRef = encodeRef;
 exports.encryptKeystore = encryptKeystore;
+exports.extractX402Metadata = extractX402Metadata;
+exports.findMatchingOption = findMatchingOption;
+exports.formatPaymentSignature = formatPaymentSignature;
 exports.getBotConfig = getBotConfig;
 exports.getChain = getChain;
 exports.getDomainSeparator = getDomainSeparator;
@@ -3945,10 +4310,16 @@ exports.isRebalanceTokenWhitelisted = isRebalanceTokenWhitelisted;
 exports.isVaultPaused = isVaultPaused;
 exports.operatorMaxDrainPerDay = operatorMaxDrainPerDay;
 exports.parseAmount = parseAmount;
+exports.parseChainId = parseChainId;
+exports.parsePaymentRequired = parsePaymentRequired;
+exports.randomNonce = randomNonce;
+exports.randomPermit2Nonce = randomPermit2Nonce;
 exports.resolveToken = resolveToken;
 exports.resolveTokenDecimals = resolveTokenDecimals;
 exports.signExecuteIntent = signExecuteIntent;
 exports.signPayment = signPayment;
+exports.signPermit2WitnessTransfer = signPermit2WitnessTransfer;
 exports.signSwapIntent = signSwapIntent;
+exports.signTransferWithAuthorization = signTransferWithAuthorization;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map