@parallel-protocol/x402-fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parallel Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @parallel-protocol/x402-fetch
+
+Payer-side x402 client for Parallel Protocol — the counterpart of the
+[`@parallel-protocol/x402`](https://github.com/parallel-protocol/sdk-merchant/tree/main/packages/x402)
+merchant middleware. It wraps `fetch` so that an x402 `402 Payment Required`
+challenge is paid automatically and the request is retried with the payment
+attached.
+
+The agent only needs a funded wallet. No payment plumbing, no protocol
+knowledge, no other setup.
+
+## Install
+
+```bash
+npm install @parallel-protocol/x402-fetch
+# or
+bun add @parallel-protocol/x402-fetch
+```
+
+## Usage
+
+```ts
+import { wrapFetchWithPayment } from "@parallel-protocol/x402-fetch";
+
+const payFetch = wrapFetchWithPayment(fetch); // key from PARALLEL_PRIVATE_KEY
+
+const res = await payFetch("https://api.example.com/premium-data");
+const data = await res.json(); // paid for and delivered
+```
+
+## How it works
+
+1. The wrapped fetch performs the request; anything but a `402` passes through
+   untouched.
+2. On `402`, it decodes and validates the merchant's invoice
+   (`payment-required` header), picks the entry matching the configured chain
+   (preferring your `payWith` token when offered), and enforces the spend cap.
+3. It builds and signs the payment **locally** through the
+   [`@parallel-protocol/cli`](https://www.npmjs.com/package/@parallel-protocol/cli)
+   engine (a regular dependency), which selects the best route — direct
+   transfer, Parallelizer swap, savings deposit/redeem — from the wallet's
+   balances.
+4. It retries the request with the `X-PAYMENT` header; the merchant verifies
+   and settles through the Parallel facilitator.
+
+Gas is sponsored by the facilitator — the wallet needs no ETH, only the
+stablecoin it pays with (USDp, USDC or sUSDp). On a paid response, the tx hash
+and route are available via the receipt helper:
+
+```ts
+import { decodePaymentResponse } from "@parallel-protocol/x402-fetch";
+
+const receipt = decodePaymentResponse(res); // { txHash, route, gasSponsored, … }
+```
+
+## Options
+
+```ts
+wrapFetchWithPayment(fetch, {
+  chain: "base",          // chain slug (default "base")
+  privateKey: "0x…",      // defaults to PARALLEL_PRIVATE_KEY
+  payWith: "usdc",        // force the spend token; default: balance-based
+  maxAmount: "1",         // per-request spend cap, whole token units (default "1")
+  timeoutMs: 60_000,      // payment-engine timeout (default 60s)
+  allowInsecure: false,   // allow plain-http merchants (localhost always allowed)
+});
+```
+
+An unknown chain slug or a missing/malformed key throws `X402FetchError` at
+wrap time, not on the first request. Payment failures reject with an
+`X402FetchError` carrying a `code` (and an `engineCode` such as
+`INSUFFICIENT_BALANCE` when the engine rejected).
+
+## Security model
+
+- **Spend is capped.** Invoices above `maxAmount` (default **1 token**) are
+  rejected before anything is signed — a compromised merchant cannot drain the
+  wallet in one request. Raise the cap deliberately, per wrapper.
+- **The invoice is not trusted.** Addresses, amounts and decimals are
+  validated; the decimals of known Parallel tokens cannot be re-declared by
+  the merchant, and invoices for a different chain fail loudly instead of
+  paying into the void.
+- **The private key never leaves your machine.** Payments are EIP-3009 typed
+  messages signed locally; only signatures travel. The key does cross the
+  process boundary to the local signing engine (a child process of your own
+  user).
+- **Plain http is refused** (except localhost) unless you opt in — an on-path
+  attacker on http could inject invoices.
+- **Use a dedicated hot wallet** funded with only what the agent needs. Any
+  code running in your process can read your environment — never point an
+  account holding significant funds at an autonomous agent.
+- A payment can settle even when the paid retry fails (network errors, merchant
+  bugs). Treat non-idempotent paid requests accordingly.
+
+## Scope & runtime
+
+Targets **Parallel merchants** (header-carried invoices, as emitted by
+`@parallel-protocol/x402`). Node and Bun; the payment engine runs as a
+subprocess of your own runtime — no global installs, no downloads at payment
+time. Payments are serialized per wrapper. Browser support and viem `Account`
+signers (hardware and remote) are planned.

package/dist/index.cjs

@@ -0,0 +1,324 @@
+'use strict';
+
+var chains = require('@parallel-protocol/chains');
+var viem = require('viem');
+var child_process = require('child_process');
+var fs = require('fs');
+var module$1 = require('module');
+var path = require('path');
+var util = require('util');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// ../../node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/types.ts
+var X402FetchError = class extends Error {
+  code;
+  /** Engine error code when the payment engine rejected, e.g. INSUFFICIENT_BALANCE. */
+  engineCode;
+  hint;
+  constructor(message, code, extra) {
+    super(message, extra?.cause !== void 0 ? { cause: extra.cause } : {});
+    this.name = "X402FetchError";
+    this.code = code;
+    if (extra?.engineCode !== void 0) this.engineCode = extra.engineCode;
+    if (extra?.hint !== void 0) this.hint = extra.hint;
+  }
+};
+
+// src/cli.ts
+var execFileAsync = util.promisify(child_process.execFile);
+function clip(value, max = 200) {
+  return String(value).replace(/[^\x20-\x7e]/g, "").slice(0, max);
+}
+function resolveCliBin() {
+  let pkgPath;
+  try {
+    const require2 = module$1.createRequire(importMetaUrl);
+    pkgPath = require2.resolve("@parallel-protocol/cli/package.json");
+  } catch (cause) {
+    throw new X402FetchError(
+      "@parallel-protocol/cli could not be resolved \u2014 is the package installed?",
+      "ENGINE_NOT_FOUND",
+      { cause }
+    );
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.parallel;
+  if (!rel) {
+    throw new X402FetchError(
+      "@parallel-protocol/cli declares no binary",
+      "ENGINE_NOT_FOUND"
+    );
+  }
+  return path__default.default.join(path__default.default.dirname(pkgPath), rel);
+}
+var cachedBin;
+async function preparePayment(params) {
+  cachedBin ??= resolveCliBin();
+  const args = [
+    cachedBin,
+    "pay",
+    "prepare",
+    "--amount",
+    params.amount,
+    "--recipient",
+    params.recipient,
+    "--token",
+    params.token,
+    "--chain",
+    params.chain,
+    "--wallet",
+    "env",
+    "--json"
+  ];
+  if (params.payWith) args.push("--pay-with", params.payWith);
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync(process.execPath, args, {
+      env: { ...process.env, PARALLEL_PRIVATE_KEY: params.privateKey },
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: params.timeoutMs,
+      killSignal: "SIGKILL",
+      ...params.signal && { signal: params.signal }
+    }));
+  } catch (err) {
+    const e = err;
+    if (e.name === "AbortError") throw err;
+    if (e.killed) {
+      throw new X402FetchError(
+        `payment engine timed out after ${params.timeoutMs}ms`,
+        "ENGINE_TIMEOUT"
+      );
+    }
+    try {
+      const parsed2 = JSON.parse(e.stderr ?? "");
+      if (parsed2.error?.code) {
+        throw new X402FetchError(
+          `payment preparation failed: ${clip(parsed2.error.message)}`,
+          "ENGINE_FAILED",
+          { engineCode: parsed2.error.code, hint: parsed2.error.hint }
+        );
+      }
+    } catch (inner) {
+      if (inner instanceof X402FetchError) throw inner;
+    }
+    throw new X402FetchError(
+      `payment preparation failed: ${clip(e.stderr?.trim() || e.message)}`,
+      "ENGINE_FAILED",
+      { cause: err }
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch (cause) {
+    throw new X402FetchError(
+      "payment engine returned unparseable output",
+      "ENGINE_FAILED",
+      { cause }
+    );
+  }
+  if (!parsed.success || !parsed.data?.encoded) {
+    throw new X402FetchError(
+      `payment preparation failed: ${clip(JSON.stringify(parsed.error ?? parsed))}`,
+      "ENGINE_FAILED"
+    );
+  }
+  return parsed.data;
+}
+
+// src/fetch.ts
+var PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var AMOUNT_RE = /^[0-9]{1,78}$/;
+var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function decodeInvoice(header) {
+  try {
+    const invoice = JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+    return Array.isArray(invoice.accepts) ? invoice : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toCliToken(asset, chain) {
+  const lower = asset.toLowerCase();
+  if (chains.getUSDpAddress(chain)?.toLowerCase() === lower) return "usdp";
+  if (chains.getUSDCAddress(chain)?.toLowerCase() === lower) return "usdc";
+  if (chains.getSUSDpAddress(chain)?.toLowerCase() === lower) return "susdp";
+  return asset;
+}
+function payWithAddress(payWith, chain) {
+  if (payWith === "usdp") return chains.getUSDpAddress(chain);
+  if (payWith === "usdc") return chains.getUSDCAddress(chain);
+  return chains.getSUSDpAddress(chain);
+}
+function selectRequirement(invoice, chain, payWith) {
+  const network = `eip155:${chains.getChainId(chain)}`;
+  const candidates = invoice.accepts.filter(
+    (r) => r && r.scheme === "exact" && r.network === network
+  );
+  if (payWith) {
+    const preferred = payWithAddress(payWith, chain)?.toLowerCase();
+    const match = candidates.find((r) => r.asset?.toLowerCase() === preferred);
+    if (match) return match;
+  }
+  return candidates[0];
+}
+function resolvePayment(requirement, chain) {
+  if (!ADDRESS_RE.test(requirement.payTo ?? "")) {
+    throw new X402FetchError(
+      "invoice payTo is not an address",
+      "INVALID_INVOICE"
+    );
+  }
+  if (!ADDRESS_RE.test(requirement.asset ?? "")) {
+    throw new X402FetchError(
+      "invoice asset is not an address",
+      "INVALID_INVOICE"
+    );
+  }
+  if (!AMOUNT_RE.test(requirement.amount ?? "")) {
+    throw new X402FetchError(
+      "invoice amount is not a positive integer string",
+      "INVALID_INVOICE"
+    );
+  }
+  const raw = BigInt(requirement.amount);
+  if (raw === 0n) {
+    throw new X402FetchError("invoice amount is zero", "INVALID_INVOICE");
+  }
+  const token = toCliToken(requirement.asset, chain);
+  const declared = requirement.extra?.decimals;
+  const catalogued = chains.getTokenDecimals(chain, requirement.asset);
+  let decimals;
+  if (catalogued !== void 0) {
+    if (declared !== void 0 && declared !== catalogued) {
+      throw new X402FetchError(
+        `invoice declares ${declared} decimals for ${token} (expected ${catalogued})`,
+        "INVALID_INVOICE"
+      );
+    }
+    decimals = catalogued;
+  } else {
+    if (declared !== void 0 && (!Number.isInteger(declared) || declared < 0 || declared > 36)) {
+      throw new X402FetchError(
+        "invoice declares implausible decimals",
+        "INVALID_INVOICE"
+      );
+    }
+    decimals = declared ?? 18;
+  }
+  return { token, amount: viem.formatUnits(raw, decimals) };
+}
+function assertSecureUrl(url, allowInsecure) {
+  const parsed = new URL(url);
+  if (parsed.protocol === "http:" && !LOCAL_HOSTNAMES.has(parsed.hostname) && !allowInsecure) {
+    throw new X402FetchError(
+      `refusing to pay an invoice served over plain http (${parsed.origin}) \u2014 use https or set allowInsecure`,
+      "INSECURE_URL"
+    );
+  }
+}
+function wrapFetchWithPayment(baseFetch, options = {}) {
+  const chain = options.chain ?? "base";
+  if (!chains.isKnownChain(chain)) {
+    throw new X402FetchError(`Unknown chain "${chain}"`, "UNKNOWN_CHAIN");
+  }
+  const privateKey = options.privateKey ?? process.env.PARALLEL_PRIVATE_KEY;
+  if (!privateKey) {
+    throw new X402FetchError(
+      "A signing key is required \u2014 pass options.privateKey or set PARALLEL_PRIVATE_KEY",
+      "NO_SIGNING_KEY"
+    );
+  }
+  if (!PRIVATE_KEY_RE.test(privateKey)) {
+    throw new X402FetchError(
+      "The signing key is not a 32-byte 0x-prefixed hex string",
+      "NO_SIGNING_KEY"
+    );
+  }
+  const maxAmount = options.maxAmount ?? "1";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  let queue = Promise.resolve();
+  const exclusive = (task) => {
+    const run = queue.then(task);
+    queue = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  return async (input, init) => {
+    const request = input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const res = await baseFetch(request.clone());
+    if (res.status !== 402) return res;
+    const header = res.headers.get("payment-required");
+    if (!header) return res;
+    const invoice = decodeInvoice(header);
+    if (!invoice) return res;
+    const requirement = selectRequirement(invoice, chain, options.payWith);
+    if (!requirement) {
+      const offered = [...new Set(invoice.accepts.map((r) => r?.network))];
+      throw new X402FetchError(
+        `invoice accepts payment on ${offered.join(", ") || "(nothing)"} but this fetch pays on ${chain}`,
+        "CHAIN_MISMATCH"
+      );
+    }
+    assertSecureUrl(request.url, options.allowInsecure ?? false);
+    const { token, amount } = resolvePayment(requirement, chain);
+    if (viem.parseUnits(amount, 36) > viem.parseUnits(maxAmount, 36)) {
+      throw new X402FetchError(
+        `invoice demands ${amount} ${token}, above the ${maxAmount} maxAmount cap`,
+        "AMOUNT_EXCEEDS_MAX"
+      );
+    }
+    const { encoded } = await exclusive(
+      () => preparePayment({
+        amount,
+        recipient: requirement.payTo,
+        token,
+        chain,
+        payWith: options.payWith,
+        privateKey,
+        timeoutMs,
+        signal: request.signal
+      })
+    );
+    const headers = new Headers(request.headers);
+    headers.set("X-PAYMENT", encoded);
+    const paid = new Request(request, {
+      headers,
+      redirect: "manual"
+    });
+    return baseFetch(paid);
+  };
+}
+
+// src/receipt.ts
+function decodePaymentResponse(res) {
+  const header = res.headers.get("payment-response");
+  if (!header) return void 0;
+  try {
+    return JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+  } catch (cause) {
+    throw new X402FetchError(
+      "payment-response header is not decodable",
+      "INVALID_INVOICE",
+      { cause }
+    );
+  }
+}
+
+exports.X402FetchError = X402FetchError;
+exports.decodePaymentResponse = decodePaymentResponse;
+exports.wrapFetchWithPayment = wrapFetchWithPayment;

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { Chain } from '@parallel-protocol/chains';
+import { Address } from 'viem';
+
+/**
+ * Minimal fetch signature this package wraps and returns. Structurally
+ * compatible with the global `fetch` without depending on ambient lib types.
+ */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** One entry of a 402 invoice's `accepts` array (x402 wire format). */
+type PaymentRequirement = {
+    scheme: string;
+    /** eip155-form chain id, e.g. "eip155:8453". */
+    network: string;
+    asset: Address;
+    /** Amount in the asset's smallest unit; its decimals travel in `extra`. */
+    amount: string;
+    payTo: Address;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        decimals?: number;
+    };
+};
+/**
+ * The decoded `payment-required` header a merchant returns with a 402.
+ * This client reads `accepts`; the other fields are wire-format documentation.
+ */
+type PaymentRequired = {
+    x402Version: number;
+    resource?: {
+        url?: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentRequirement[];
+    error?: string;
+};
+/** The merchant's `payment-response` receipt on a settled request. */
+type PaymentReceipt = {
+    txHash: string;
+    route: string;
+    chain?: string;
+    networkId?: string;
+    gasSponsored?: boolean;
+};
+/** Token the agent spends, overriding balance-based selection. */
+type PayWith = "usdp" | "usdc" | "susdp";
+type WrapFetchOptions = {
+    /** Chain slug the agent pays on (default: "base"). */
+    chain?: Chain;
+    /**
+     * Hot-wallet signing key; defaults to the `PARALLEL_PRIVATE_KEY` environment
+     * variable. The key never leaves this machine — only signatures are sent.
+     */
+    privateKey?: string;
+    /** Force which token to spend; defaults to balance-based selection. */
+    payWith?: PayWith;
+    /**
+     * Maximum spend per request, in whole token units (default: "1").
+     * Invoices above the cap are rejected before anything is signed.
+     */
+    maxAmount?: string;
+    /** Payment-engine timeout in milliseconds (default: 60_000). */
+    timeoutMs?: number;
+    /**
+     * Allow paying invoices served over plain http (default: false).
+     * Localhost is always allowed.
+     */
+    allowInsecure?: boolean;
+};
+type X402FetchErrorCode = "NO_SIGNING_KEY" | "UNKNOWN_CHAIN" | "CHAIN_MISMATCH" | "INVALID_INVOICE" | "AMOUNT_EXCEEDS_MAX" | "INSECURE_URL" | "ENGINE_NOT_FOUND" | "ENGINE_TIMEOUT" | "ENGINE_FAILED";
+declare class X402FetchError extends Error {
+    readonly code: X402FetchErrorCode;
+    /** Engine error code when the payment engine rejected, e.g. INSUFFICIENT_BALANCE. */
+    readonly engineCode?: string;
+    readonly hint?: string;
+    constructor(message: string, code: X402FetchErrorCode, extra?: {
+        engineCode?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * Wrap a `fetch` so that an x402 `402 Payment Required` is paid automatically
+ * and the request is retried with the payment attached. The returned function
+ * is a drop-in `fetch` replacement — non-402 responses pass through untouched.
+ *
+ * @param baseFetch - The `fetch` implementation to wrap (usually the global).
+ * @param options - Chain, signing key and spend-policy overrides.
+ * @returns A `fetch` that settles 402 challenges transparently.
+ * @throws {X402FetchError} At wrap time if the chain is unknown or no valid
+ * signing key is available. Payment failures reject the returned promise.
+ *
+ * @example
+ * const payFetch = wrapFetchWithPayment(fetch); // key from PARALLEL_PRIVATE_KEY
+ * const res = await payFetch("https://api.example.com/premium-data");
+ */
+declare function wrapFetchWithPayment(baseFetch: FetchLike, options?: WrapFetchOptions): FetchLike;
+
+/**
+ * Decode the merchant's `payment-response` receipt (tx hash, route, gas
+ * sponsorship) from a paid response. Returns `undefined` when the header is
+ * absent — i.e. the request did not go through a payment.
+ */
+declare function decodePaymentResponse(res: Response): PaymentReceipt | undefined;
+
+export { type FetchLike, type PayWith, type PaymentReceipt, type PaymentRequired, type PaymentRequirement, type WrapFetchOptions, X402FetchError, type X402FetchErrorCode, decodePaymentResponse, wrapFetchWithPayment };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { Chain } from '@parallel-protocol/chains';
+import { Address } from 'viem';
+
+/**
+ * Minimal fetch signature this package wraps and returns. Structurally
+ * compatible with the global `fetch` without depending on ambient lib types.
+ */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** One entry of a 402 invoice's `accepts` array (x402 wire format). */
+type PaymentRequirement = {
+    scheme: string;
+    /** eip155-form chain id, e.g. "eip155:8453". */
+    network: string;
+    asset: Address;
+    /** Amount in the asset's smallest unit; its decimals travel in `extra`. */
+    amount: string;
+    payTo: Address;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        decimals?: number;
+    };
+};
+/**
+ * The decoded `payment-required` header a merchant returns with a 402.
+ * This client reads `accepts`; the other fields are wire-format documentation.
+ */
+type PaymentRequired = {
+    x402Version: number;
+    resource?: {
+        url?: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentRequirement[];
+    error?: string;
+};
+/** The merchant's `payment-response` receipt on a settled request. */
+type PaymentReceipt = {
+    txHash: string;
+    route: string;
+    chain?: string;
+    networkId?: string;
+    gasSponsored?: boolean;
+};
+/** Token the agent spends, overriding balance-based selection. */
+type PayWith = "usdp" | "usdc" | "susdp";
+type WrapFetchOptions = {
+    /** Chain slug the agent pays on (default: "base"). */
+    chain?: Chain;
+    /**
+     * Hot-wallet signing key; defaults to the `PARALLEL_PRIVATE_KEY` environment
+     * variable. The key never leaves this machine — only signatures are sent.
+     */
+    privateKey?: string;
+    /** Force which token to spend; defaults to balance-based selection. */
+    payWith?: PayWith;
+    /**
+     * Maximum spend per request, in whole token units (default: "1").
+     * Invoices above the cap are rejected before anything is signed.
+     */
+    maxAmount?: string;
+    /** Payment-engine timeout in milliseconds (default: 60_000). */
+    timeoutMs?: number;
+    /**
+     * Allow paying invoices served over plain http (default: false).
+     * Localhost is always allowed.
+     */
+    allowInsecure?: boolean;
+};
+type X402FetchErrorCode = "NO_SIGNING_KEY" | "UNKNOWN_CHAIN" | "CHAIN_MISMATCH" | "INVALID_INVOICE" | "AMOUNT_EXCEEDS_MAX" | "INSECURE_URL" | "ENGINE_NOT_FOUND" | "ENGINE_TIMEOUT" | "ENGINE_FAILED";
+declare class X402FetchError extends Error {
+    readonly code: X402FetchErrorCode;
+    /** Engine error code when the payment engine rejected, e.g. INSUFFICIENT_BALANCE. */
+    readonly engineCode?: string;
+    readonly hint?: string;
+    constructor(message: string, code: X402FetchErrorCode, extra?: {
+        engineCode?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * Wrap a `fetch` so that an x402 `402 Payment Required` is paid automatically
+ * and the request is retried with the payment attached. The returned function
+ * is a drop-in `fetch` replacement — non-402 responses pass through untouched.
+ *
+ * @param baseFetch - The `fetch` implementation to wrap (usually the global).
+ * @param options - Chain, signing key and spend-policy overrides.
+ * @returns A `fetch` that settles 402 challenges transparently.
+ * @throws {X402FetchError} At wrap time if the chain is unknown or no valid
+ * signing key is available. Payment failures reject the returned promise.
+ *
+ * @example
+ * const payFetch = wrapFetchWithPayment(fetch); // key from PARALLEL_PRIVATE_KEY
+ * const res = await payFetch("https://api.example.com/premium-data");
+ */
+declare function wrapFetchWithPayment(baseFetch: FetchLike, options?: WrapFetchOptions): FetchLike;
+
+/**
+ * Decode the merchant's `payment-response` receipt (tx hash, route, gas
+ * sponsorship) from a paid response. Returns `undefined` when the header is
+ * absent — i.e. the request did not go through a payment.
+ */
+declare function decodePaymentResponse(res: Response): PaymentReceipt | undefined;
+
+export { type FetchLike, type PayWith, type PaymentReceipt, type PaymentRequired, type PaymentRequirement, type WrapFetchOptions, X402FetchError, type X402FetchErrorCode, decodePaymentResponse, wrapFetchWithPayment };

package/dist/index.js

@@ -0,0 +1,314 @@
+import { isKnownChain, getChainId, getTokenDecimals, getUSDpAddress, getUSDCAddress, getSUSDpAddress } from '@parallel-protocol/chains';
+import { parseUnits, formatUnits } from 'viem';
+import { execFile } from 'child_process';
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+import { promisify } from 'util';
+
+// src/fetch.ts
+
+// src/types.ts
+var X402FetchError = class extends Error {
+  code;
+  /** Engine error code when the payment engine rejected, e.g. INSUFFICIENT_BALANCE. */
+  engineCode;
+  hint;
+  constructor(message, code, extra) {
+    super(message, extra?.cause !== void 0 ? { cause: extra.cause } : {});
+    this.name = "X402FetchError";
+    this.code = code;
+    if (extra?.engineCode !== void 0) this.engineCode = extra.engineCode;
+    if (extra?.hint !== void 0) this.hint = extra.hint;
+  }
+};
+
+// src/cli.ts
+var execFileAsync = promisify(execFile);
+function clip(value, max = 200) {
+  return String(value).replace(/[^\x20-\x7e]/g, "").slice(0, max);
+}
+function resolveCliBin() {
+  let pkgPath;
+  try {
+    const require2 = createRequire(import.meta.url);
+    pkgPath = require2.resolve("@parallel-protocol/cli/package.json");
+  } catch (cause) {
+    throw new X402FetchError(
+      "@parallel-protocol/cli could not be resolved \u2014 is the package installed?",
+      "ENGINE_NOT_FOUND",
+      { cause }
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.parallel;
+  if (!rel) {
+    throw new X402FetchError(
+      "@parallel-protocol/cli declares no binary",
+      "ENGINE_NOT_FOUND"
+    );
+  }
+  return path.join(path.dirname(pkgPath), rel);
+}
+var cachedBin;
+async function preparePayment(params) {
+  cachedBin ??= resolveCliBin();
+  const args = [
+    cachedBin,
+    "pay",
+    "prepare",
+    "--amount",
+    params.amount,
+    "--recipient",
+    params.recipient,
+    "--token",
+    params.token,
+    "--chain",
+    params.chain,
+    "--wallet",
+    "env",
+    "--json"
+  ];
+  if (params.payWith) args.push("--pay-with", params.payWith);
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsync(process.execPath, args, {
+      env: { ...process.env, PARALLEL_PRIVATE_KEY: params.privateKey },
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: params.timeoutMs,
+      killSignal: "SIGKILL",
+      ...params.signal && { signal: params.signal }
+    }));
+  } catch (err) {
+    const e = err;
+    if (e.name === "AbortError") throw err;
+    if (e.killed) {
+      throw new X402FetchError(
+        `payment engine timed out after ${params.timeoutMs}ms`,
+        "ENGINE_TIMEOUT"
+      );
+    }
+    try {
+      const parsed2 = JSON.parse(e.stderr ?? "");
+      if (parsed2.error?.code) {
+        throw new X402FetchError(
+          `payment preparation failed: ${clip(parsed2.error.message)}`,
+          "ENGINE_FAILED",
+          { engineCode: parsed2.error.code, hint: parsed2.error.hint }
+        );
+      }
+    } catch (inner) {
+      if (inner instanceof X402FetchError) throw inner;
+    }
+    throw new X402FetchError(
+      `payment preparation failed: ${clip(e.stderr?.trim() || e.message)}`,
+      "ENGINE_FAILED",
+      { cause: err }
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch (cause) {
+    throw new X402FetchError(
+      "payment engine returned unparseable output",
+      "ENGINE_FAILED",
+      { cause }
+    );
+  }
+  if (!parsed.success || !parsed.data?.encoded) {
+    throw new X402FetchError(
+      `payment preparation failed: ${clip(JSON.stringify(parsed.error ?? parsed))}`,
+      "ENGINE_FAILED"
+    );
+  }
+  return parsed.data;
+}
+
+// src/fetch.ts
+var PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var AMOUNT_RE = /^[0-9]{1,78}$/;
+var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function decodeInvoice(header) {
+  try {
+    const invoice = JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+    return Array.isArray(invoice.accepts) ? invoice : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toCliToken(asset, chain) {
+  const lower = asset.toLowerCase();
+  if (getUSDpAddress(chain)?.toLowerCase() === lower) return "usdp";
+  if (getUSDCAddress(chain)?.toLowerCase() === lower) return "usdc";
+  if (getSUSDpAddress(chain)?.toLowerCase() === lower) return "susdp";
+  return asset;
+}
+function payWithAddress(payWith, chain) {
+  if (payWith === "usdp") return getUSDpAddress(chain);
+  if (payWith === "usdc") return getUSDCAddress(chain);
+  return getSUSDpAddress(chain);
+}
+function selectRequirement(invoice, chain, payWith) {
+  const network = `eip155:${getChainId(chain)}`;
+  const candidates = invoice.accepts.filter(
+    (r) => r && r.scheme === "exact" && r.network === network
+  );
+  if (payWith) {
+    const preferred = payWithAddress(payWith, chain)?.toLowerCase();
+    const match = candidates.find((r) => r.asset?.toLowerCase() === preferred);
+    if (match) return match;
+  }
+  return candidates[0];
+}
+function resolvePayment(requirement, chain) {
+  if (!ADDRESS_RE.test(requirement.payTo ?? "")) {
+    throw new X402FetchError(
+      "invoice payTo is not an address",
+      "INVALID_INVOICE"
+    );
+  }
+  if (!ADDRESS_RE.test(requirement.asset ?? "")) {
+    throw new X402FetchError(
+      "invoice asset is not an address",
+      "INVALID_INVOICE"
+    );
+  }
+  if (!AMOUNT_RE.test(requirement.amount ?? "")) {
+    throw new X402FetchError(
+      "invoice amount is not a positive integer string",
+      "INVALID_INVOICE"
+    );
+  }
+  const raw = BigInt(requirement.amount);
+  if (raw === 0n) {
+    throw new X402FetchError("invoice amount is zero", "INVALID_INVOICE");
+  }
+  const token = toCliToken(requirement.asset, chain);
+  const declared = requirement.extra?.decimals;
+  const catalogued = getTokenDecimals(chain, requirement.asset);
+  let decimals;
+  if (catalogued !== void 0) {
+    if (declared !== void 0 && declared !== catalogued) {
+      throw new X402FetchError(
+        `invoice declares ${declared} decimals for ${token} (expected ${catalogued})`,
+        "INVALID_INVOICE"
+      );
+    }
+    decimals = catalogued;
+  } else {
+    if (declared !== void 0 && (!Number.isInteger(declared) || declared < 0 || declared > 36)) {
+      throw new X402FetchError(
+        "invoice declares implausible decimals",
+        "INVALID_INVOICE"
+      );
+    }
+    decimals = declared ?? 18;
+  }
+  return { token, amount: formatUnits(raw, decimals) };
+}
+function assertSecureUrl(url, allowInsecure) {
+  const parsed = new URL(url);
+  if (parsed.protocol === "http:" && !LOCAL_HOSTNAMES.has(parsed.hostname) && !allowInsecure) {
+    throw new X402FetchError(
+      `refusing to pay an invoice served over plain http (${parsed.origin}) \u2014 use https or set allowInsecure`,
+      "INSECURE_URL"
+    );
+  }
+}
+function wrapFetchWithPayment(baseFetch, options = {}) {
+  const chain = options.chain ?? "base";
+  if (!isKnownChain(chain)) {
+    throw new X402FetchError(`Unknown chain "${chain}"`, "UNKNOWN_CHAIN");
+  }
+  const privateKey = options.privateKey ?? process.env.PARALLEL_PRIVATE_KEY;
+  if (!privateKey) {
+    throw new X402FetchError(
+      "A signing key is required \u2014 pass options.privateKey or set PARALLEL_PRIVATE_KEY",
+      "NO_SIGNING_KEY"
+    );
+  }
+  if (!PRIVATE_KEY_RE.test(privateKey)) {
+    throw new X402FetchError(
+      "The signing key is not a 32-byte 0x-prefixed hex string",
+      "NO_SIGNING_KEY"
+    );
+  }
+  const maxAmount = options.maxAmount ?? "1";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  let queue = Promise.resolve();
+  const exclusive = (task) => {
+    const run = queue.then(task);
+    queue = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  return async (input, init) => {
+    const request = input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const res = await baseFetch(request.clone());
+    if (res.status !== 402) return res;
+    const header = res.headers.get("payment-required");
+    if (!header) return res;
+    const invoice = decodeInvoice(header);
+    if (!invoice) return res;
+    const requirement = selectRequirement(invoice, chain, options.payWith);
+    if (!requirement) {
+      const offered = [...new Set(invoice.accepts.map((r) => r?.network))];
+      throw new X402FetchError(
+        `invoice accepts payment on ${offered.join(", ") || "(nothing)"} but this fetch pays on ${chain}`,
+        "CHAIN_MISMATCH"
+      );
+    }
+    assertSecureUrl(request.url, options.allowInsecure ?? false);
+    const { token, amount } = resolvePayment(requirement, chain);
+    if (parseUnits(amount, 36) > parseUnits(maxAmount, 36)) {
+      throw new X402FetchError(
+        `invoice demands ${amount} ${token}, above the ${maxAmount} maxAmount cap`,
+        "AMOUNT_EXCEEDS_MAX"
+      );
+    }
+    const { encoded } = await exclusive(
+      () => preparePayment({
+        amount,
+        recipient: requirement.payTo,
+        token,
+        chain,
+        payWith: options.payWith,
+        privateKey,
+        timeoutMs,
+        signal: request.signal
+      })
+    );
+    const headers = new Headers(request.headers);
+    headers.set("X-PAYMENT", encoded);
+    const paid = new Request(request, {
+      headers,
+      redirect: "manual"
+    });
+    return baseFetch(paid);
+  };
+}
+
+// src/receipt.ts
+function decodePaymentResponse(res) {
+  const header = res.headers.get("payment-response");
+  if (!header) return void 0;
+  try {
+    return JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+  } catch (cause) {
+    throw new X402FetchError(
+      "payment-response header is not decodable",
+      "INVALID_INVOICE",
+      { cause }
+    );
+  }
+}
+
+export { X402FetchError, decodePaymentResponse, wrapFetchWithPayment };

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@parallel-protocol/x402-fetch",
+	"version": "0.1.0",
+	"description": "Payer-side x402 client for Parallel Protocol — wraps fetch so a 402 challenge is paid automatically; the agent only needs a funded wallet",
+	"author": "Parallel Protocol <contact@parallel.best>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/parallel-protocol/sdk-merchant.git",
+		"directory": "packages/x402-fetch"
+	},
+	"keywords": [
+		"x402",
+		"402",
+		"agent-payments",
+		"stablecoin",
+		"fetch",
+		"parallel-protocol"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"homepage": "https://github.com/parallel-protocol/sdk-merchant",
+	"bugs": {
+		"url": "https://github.com/parallel-protocol/sdk-merchant/issues"
+	},
+	"license": "MIT",
+	"sideEffects": false,
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"clean": "rm -rf dist coverage",
+		"type-check": "tsc --noEmit",
+		"test": "vitest"
+	},
+	"dependencies": {
+		"@parallel-protocol/chains": "^0.2.0",
+		"@parallel-protocol/cli": "^0.2.3"
+	},
+	"peerDependencies": {
+		"viem": "^2.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"tsup": "^8.0.0",
+		"typescript": "^5.9.0",
+		"viem": "^2.47.0",
+		"vitest": "^4.0.14"
+	}
+}