feat: add x402 challenge detection and human-in-the-loop payment

Detect x402 on-chain payment challenges (X-Payment-Required: x402 header)
alongside existing L402 Lightning challenges. When an x402 challenge is
detected, parse the payment details (receiver, network, asset, amount)
and present them to the agent for human-in-the-loop payment. After the
user completes payment, the txHash parameter allows retrying the request
with the X-Payment header for server verification.

Author: TheCryptoDonkey

CLAUDE.md

@@ -52,6 +52,7 @@ src/
   wallet/               # Payment implementations (NWC, Cashu melt, human)
   store/                # Persistent JSON stores (credentials, Cashu tokens)
   l402/                 # L402 protocol utilities (parse, detect, cache, bolt11)
+  x402/                 # x402 protocol utilities (parse, payment deeplinks)
 tests/                  # Tests mirror src/ structure (tests/tools/, tests/wallet/, etc.)
   e2e/                  # Integration tests against in-process toll-booth
 ```

package.json

@@ -11,6 +11,7 @@
     ".": "./build/index.js",
     "./tools/*": "./build/tools/*.js",
     "./l402/*": "./build/l402/*.js",
+    "./x402/*": "./build/x402/*.js",
     "./store/*": "./build/store/*.js",
     "./fetch/*": "./build/fetch/*.js",
     "./spend-tracker": "./build/spend-tracker.js"

src/index.ts

@@ -25,6 +25,8 @@ import { registerBuyCreditsTool } from './tools/buy-credits.js'
 import { registerRedeemCashuTool } from './tools/redeem-cashu.js'
 import { registerSearchTool } from './tools/search.js'
 import { createNostrSubscriber } from './tools/nostr-subscribe.js'
+import { isX402Challenge, parseX402Challenge } from './x402/parse.js'
+import { formatX402PaymentRequest } from './x402/payment.js'
 import { createResilientFetch, withTransportFallback } from './fetch/resilient-fetch.js'
 import { selectTransports } from './fetch/transport.js'
 import { resolveHns as resolveHnsBase } from './fetch/hns-resolve.js'
@@ -180,6 +182,9 @@ registerFetchTool(server, {
   challengeCache,
   generateQr,
   walletMethod: () => getWallet()?.method,
+  isX402: isX402Challenge,
+  parseX402: parseX402Challenge,
+  formatX402: formatX402PaymentRequest,
 })
 
 registerPayTool(server, {

src/tools/fetch.ts

@@ -8,6 +8,7 @@ import type { ResilientFetchOptions } from '../fetch/resilient-fetch.js'
 import type { SpendTracker } from '../spend-tracker.js'
 import type { ChallengeCache } from '../l402/challenge-cache.js'
 import type { WalletMethod } from '../wallet/types.js'
+import type { X402Challenge } from '../x402/parse.js'
 import { safeErrorMessage } from './safe-error.js'
 import { filterResponseHeaders } from './safe-headers.js'
 
@@ -35,6 +36,12 @@ export interface FetchDeps {
   challengeCache: ChallengeCache
   generateQr: (invoice: string) => Promise<{ png: string; text: string }>
   walletMethod: () => WalletMethod | undefined
+  /** Detects x402 challenge from response headers. */
+  isX402: (headers: Headers) => boolean
+  /** Parses x402 challenge details from the response body. */
+  parseX402: (body: unknown) => X402Challenge | null
+  /** Formats x402 challenge as a payment request for the agent. */
+  formatX402: (challenge: X402Challenge) => { json: Record<string, unknown>; message: string }
 }
 
 function parseBalance(value: string | null): number | null {
@@ -43,9 +50,9 @@ function parseBalance(value: string | null): number | null {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : null
 }
 
-/** Makes an HTTP request with automatic L402 payment and credential reuse. Pays the invoice if within budget, stores the credential, and retries. */
+/** Makes an HTTP request with automatic L402/x402 payment and credential reuse. Pays the invoice if within budget, stores the credential, and retries. */
 export async function handleFetch(
-  args: { url: string; urls?: string[]; method?: string; headers?: Record<string, string>; body?: string; autoPay?: boolean; pubkey?: string },
+  args: { url: string; urls?: string[]; method?: string; headers?: Record<string, string>; body?: string; autoPay?: boolean; pubkey?: string; txHash?: string },
   deps: FetchDeps,
 ) {
   // When multiple URLs are provided (from l402_search results), use transport fallback.
@@ -73,6 +80,13 @@ export async function handleFetch(
     deps.credentialStore.updateLastUsed(credKey)
   }
 
+  // x402 retry: when the caller provides a transaction hash from a completed
+  // on-chain payment, attach it as the X-Payment header so the server can
+  // verify and grant access.
+  if (args.txHash) {
+    reqHeaders['X-Payment'] = args.txHash
+  }
+
   // Build a unified fetch helper: multi-URL (transport fallback) or single-URL
   const doFetch = (url: string, init: RequestInit) => {
     const allUrls = args.urls?.length ? args.urls : [url]
@@ -111,13 +125,29 @@ export async function handleFetch(
       }
     }
 
-    // 402 response - parse the challenge
-    const authHeader = response.headers.get('www-authenticate') ?? ''
-    const challenge = deps.parseL402(authHeader)
-
+    // 402 response - parse the challenge body (shared by L402 and x402 paths)
     let challengeBody: Record<string, unknown> = {}
     try { challengeBody = await response.json() as Record<string, unknown> } catch { /* non-JSON 402 body */ }
 
+    // x402 challenge: on-chain stablecoin payment (human-in-the-loop)
+    if (deps.isX402(response.headers)) {
+      const x402 = deps.parseX402(challengeBody)
+      if (x402) {
+        const { json } = deps.formatX402(x402)
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(json, null, 2),
+          }],
+        }
+      }
+      // Header said x402 but body was unparseable — fall through to generic 402
+    }
+
+    // L402 challenge: Lightning payment
+    const authHeader = response.headers.get('www-authenticate') ?? ''
+    const challenge = deps.parseL402(authHeader)
+
     const decoded = challenge ? deps.decodeBolt11(challenge.invoice) : { costSats: null, paymentHash: null, expiry: 3600 }
     const serverInfo = deps.detectServer(response.headers, challengeBody)
 
@@ -320,7 +350,7 @@ export function registerFetchTool(server: McpServer, deps: FetchDeps): void {
   server.registerTool(
     'l402_fetch',
     {
-      description: 'Fetch a URL with automatic payment handling. Use this to access any paid API or service. Manages credentials, pays automatically when autoPay is true and cost is within budget, and retries. For human wallets, returns a payment page URL or QR code. Set autoPay to true for seamless access. When a 402 is returned with tiers, present the pricing options to the user and use l402_buy_credits to purchase their chosen tier.',
+      description: 'Fetch a URL with automatic payment handling (L402 Lightning + x402 on-chain). Manages credentials, pays automatically when autoPay is true and cost is within budget, and retries. For human wallets, returns a payment page URL or QR code. For x402 services, returns payment details (receiver address, network, asset, amount) — the user pays in their wallet and provides the transaction hash. Set autoPay to true for seamless access. When a 402 is returned with tiers, present the pricing options to the user and use l402_buy_credits to purchase their chosen tier.',
       inputSchema: {
         url: z.url().describe('The primary URL to request. When using search results, pass the first URL here and all URLs in the urls field.'),
         urls: z.array(z.url()).max(10).optional().describe('All transport URLs from l402_search results (clearnet, onion, HNS). When present, transports are tried in preference order with automatic fallback on connection failure.'),
@@ -329,6 +359,7 @@ export function registerFetchTool(server: McpServer, deps: FetchDeps): void {
         body: z.string().max(1_000_000).optional().describe('Request body (for POST/PUT)'),
         autoPay: z.boolean().optional().default(false).describe('Automatically pay if within MAX_AUTO_PAY_SATS budget'),
         pubkey: z.string().max(128).optional().describe('Service pubkey from l402_search results — used to share credentials across all transport URLs for the same service'),
+        txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/).optional().describe('Transaction hash from a completed x402 on-chain payment. When provided, retries the request with X-Payment header for server verification.'),
       },
     },
     async (args) => handleFetch(args, deps),

src/x402/parse.ts

@@ -0,0 +1,89 @@
+/** Chain IDs for supported EVM networks. */
+const CHAIN_IDS: Record<string, number> = {
+  base: 8453,
+  'base-sepolia': 84532,
+  ethereum: 1,
+  optimism: 10,
+  arbitrum: 42161,
+  polygon: 137,
+}
+
+/** Decimal places per asset for converting human-readable amounts to smallest unit. */
+const ASSET_DECIMALS: Record<string, number> = {
+  usdc: 6,
+  usdt: 6,
+  dai: 18,
+  eth: 18,
+}
+
+export interface X402Challenge {
+  receiver: string
+  network: string
+  asset: string
+  amountUsd: number
+  /** EVM chain ID for the network (e.g. 8453 for Base). */
+  chainId: number | null
+  /** Amount in smallest asset unit (e.g. 1000000 for 1 USDC). */
+  amountSmallestUnit: bigint | null
+}
+
+const ETH_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/
+
+/** Detects whether a 402 response contains an x402 challenge via the X-Payment-Required header. */
+export function isX402Challenge(headers: Headers): boolean {
+  const value = headers.get('x-payment-required')
+  return value?.toLowerCase() === 'x402'
+}
+
+/**
+ * Parses an x402 challenge from the response body.
+ * Expected shape: `{ x402: { receiver, network, asset, amount_usd } }`.
+ */
+export function parseX402Challenge(body: unknown): X402Challenge | null {
+  if (body === null || typeof body !== 'object') return null
+
+  const root = body as Record<string, unknown>
+  const x402 = root.x402
+  if (x402 === null || typeof x402 !== 'object') return null
+
+  const data = x402 as Record<string, unknown>
+
+  const receiver = typeof data.receiver === 'string' ? data.receiver.trim() : null
+  const network = typeof data.network === 'string' ? data.network.trim().toLowerCase() : null
+  const asset = typeof data.asset === 'string' ? data.asset.trim().toLowerCase() : null
+
+  // Accept both amount_usd and amountUsd
+  const rawAmount = data.amount_usd ?? data.amountUsd
+  const amountUsd = typeof rawAmount === 'number' && Number.isFinite(rawAmount) && rawAmount > 0
+    ? rawAmount
+    : null
+
+  if (!receiver || !network || !asset || amountUsd === null) return null
+
+  // Validate Ethereum address format
+  if (!ETH_ADDRESS_RE.test(receiver)) return null
+
+  const chainId = CHAIN_IDS[network] ?? null
+  const decimals = ASSET_DECIMALS[asset]
+  const amountSmallestUnit = decimals !== undefined
+    ? BigInt(Math.round(amountUsd * 10 ** decimals))
+    : null
+
+  return {
+    receiver,
+    network,
+    asset,
+    amountUsd,
+    chainId,
+    amountSmallestUnit,
+  }
+}
+
+/** Builds an EIP-681 payment deeplink for wallet apps. */
+export function buildPaymentDeeplink(challenge: X402Challenge): string | null {
+  if (!challenge.chainId) return null
+
+  // For ERC-20 tokens (not native ETH), use the transfer function call format
+  // For now, return a simple ethereum: URI that most wallets understand
+  return `ethereum:${challenge.receiver}@${challenge.chainId}`
+}

src/x402/payment.ts

@@ -0,0 +1,36 @@
+import type { X402Challenge } from './parse.js'
+import { buildPaymentDeeplink } from './parse.js'
+
+/** Format the x402 challenge as a human-readable payment request for the agent to present. */
+export function formatX402PaymentRequest(challenge: X402Challenge): {
+  /** Structured JSON for the agent to parse. */
+  json: Record<string, unknown>
+  /** Human-readable summary. */
+  message: string
+} {
+  const deeplink = buildPaymentDeeplink(challenge)
+
+  const json: Record<string, unknown> = {
+    status: 402,
+    protocol: 'x402',
+    receiver: challenge.receiver,
+    network: challenge.network,
+    asset: challenge.asset.toUpperCase(),
+    amountUsd: challenge.amountUsd,
+    ...(challenge.chainId !== null ? { chainId: challenge.chainId } : {}),
+    ...(deeplink ? { paymentDeeplink: deeplink } : {}),
+    message: `Payment required: $${challenge.amountUsd} ${challenge.asset.toUpperCase()} on ${challenge.network}. `
+      + `Send to ${challenge.receiver}. `
+      + `After payment, provide the transaction hash to retry the request.`,
+  }
+
+  return {
+    json,
+    message: json.message as string,
+  }
+}
+
+/** Validate a transaction hash format (0x-prefixed hex, 32 bytes). */
+export function isValidTxHash(hash: string): boolean {
+  return /^0x[0-9a-fA-F]{64}$/.test(hash)
+}

tests/tools/fetch-security.test.ts

@@ -13,6 +13,7 @@ function makeDeps(overrides: Partial<FetchDeps> = {}): FetchDeps {
       updateLastUsed: vi.fn(),
     } as unknown as FetchDeps['credentialStore'],
     fetchFn: vi.fn() as unknown as typeof fetch,
+    transportFetch: vi.fn() as unknown as FetchDeps['transportFetch'],
     payInvoice: vi.fn().mockResolvedValue({ paid: false, method: 'none' }),
     maxAutoPaySats: 100,
     maxSpendPerMinuteSats: 10000,
@@ -23,6 +24,9 @@ function makeDeps(overrides: Partial<FetchDeps> = {}): FetchDeps {
     challengeCache: new ChallengeCache(),
     generateQr: vi.fn().mockResolvedValue({ png: 'data:image/png;base64,test', text: '█▀▀█' }),
     walletMethod: () => undefined,
+    isX402: vi.fn().mockReturnValue(false),
+    parseX402: vi.fn().mockReturnValue(null),
+    formatX402: vi.fn().mockReturnValue({ json: {}, message: '' }),
     ...overrides,
   }
 }