@fatstack/x402 0.0.1 → 0.1.0

package/README.md

@@ -1,10 +1,118 @@
 # @fatstack/x402
 
-**Reserved, launching soon.**
+Pay-per-call tooling for AI agents. **USDC on Base**, over the
+[x402](https://x402.org) protocol.
 
-This package name is reserved for [Fatstack](https://fatstack.net) — a non-custodial
-marketplace where AI agents discover and pay for API and MCP tool calls in USDC via the
-x402 protocol on Base.
+Two entry points: a **paywall** for providers, and a **spend-guarded fetch** for agents.
 
-When published, this package will provide the x402 provider middleware and the paying
-agent client. It contains no functional code yet.
+Protocol work — signing, verification, settlement — is delegated to the official
+`@x402/*` packages. This package adds the parts they leave to you: a provider-shaped
+config, a human-readable 402 body, a killswitch, an indexing reference, and spend guards
+that refuse a call _before_ anything is signed.
+
+> **Payments are final. There are no refunds.** A payment is a direct on-chain transfer
+> between two wallets. Once settled, nobody — including Fatstack — can reverse it.
+
+> **Non-custodial.** Funds move from the agent's wallet to the provider's wallet.
+> This package never holds funds and never sees a private key.
+
+## Providers: paywall a route
+
+```ts
+import { paywall } from '@fatstack/x402/provider';
+
+const pay = paywall({ price: '0.002', wallet: '0xYourWallet', toolId: 'sentiment' });
+
+app.use('*', pay.hono()); // Hono
+app.use(pay.express()); // Express
+export const POST = pay.next(handler); // Next.js route handler
+```
+
+That is the whole integration. Unpaid requests get a 402 quoting `0.002` USDC payable to
+**your** wallet, with the no-refunds notice and a docs link. Paid requests are verified and
+settled through the hosted facilitator, then passed through with an
+`X-Fatstack-Payment-Ref` header for indexing.
+
+## Agents: pay for a call, under guards
+
+```ts
+import { payFetch } from '@fatstack/x402/client';
+
+const res = await payFetch(
+  'https://sentiment.fatstack.net/run',
+  { method: 'POST' },
+  {
+    wallet: account, // any viem account; we never see your key
+    guards: {
+      maxPerCall: 0.01,
+      maxPerHour: 1,
+      maxPerDay: 10, // USD
+      allowedHosts: ['fatstack.net'],
+    },
+  },
+);
+```
+
+Exceeding any guard throws `SpendGuardError` **before a payment is signed**. Because
+payments are irreversible, the guard is the last point at which a spend can be stopped —
+so it runs on the quote, not after the fact.
+
+## Guards
+
+| Guard          | Enforced                                                          |
+| -------------- | ----------------------------------------------------------------- |
+| `allowedHosts` | Before any network call. A subdomain of a listed host is allowed. |
+| `maxPerCall`   | On the quoted price, before signing.                              |
+| `maxPerHour`   | Rolling 60 minutes, quote + prior spend, before signing.          |
+| `maxPerDay`    | Rolling 24 hours, quote + prior spend, before signing.            |
+
+Counters live in a `SpendStore`. The default is in-memory and **per process** — an agent
+running as several processes enforces a separate budget in each. Pass your own store
+(Redis, a Durable Object, Postgres) to share one budget:
+
+```ts
+import { createMemorySpendStore, type SpendStore } from '@fatstack/x402';
+```
+
+A quote in an asset the package cannot price fails closed: it throws rather than guess
+decimals, because guessing could let an unknown token slip past a cap.
+
+## Environment
+
+| Variable              | Meaning                                                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `FACILITATOR_URL`     | Hosted facilitator. Defaults to `https://x402.org/facilitator`.                                                             |
+| `FACILITATOR_API_KEY` | Sent as a bearer token to the facilitator, if set.                                                                          |
+| `KILLSWITCH`          | `1` takes every paywalled route offline with a 503, taking no payment.                                                      |
+| `FEE_MODE`            | `direct` (default) pays the provider wallet with a 0% fee. `splitter` throws — there is no splitter contract in this build. |
+
+## Framework adapters
+
+`@x402/hono`, `@x402/express` and `@x402/next` are **optional peer dependencies**, loaded
+only when you call that adapter. Install the one you use:
+
+```bash
+pnpm add @fatstack/x402 @x402/hono
+```
+
+`pay.next()` requires `@x402/next`, which needs **Next.js ≥ 16.2.6** (upstream peer
+requirement). The Hono and Express adapters have no such constraint.
+
+## Testing your integration
+
+```ts
+import { createMockFacilitator } from '@fatstack/x402/testing';
+
+const pay = paywall({ ...config, facilitator: createMockFacilitator() });
+// or: createMockFacilitator({ invalidReason: 'insufficient_funds' })
+```
+
+Nothing in the mock touches a chain or a network.
+
+## Local development
+
+```bash
+pnpm --filter @fatstack/x402 build      # tsup -> dist (ESM + CJS + d.ts)
+pnpm --filter @fatstack/x402 test
+pnpm --filter @fatstack/x402 typecheck
+```

package/dist/chunk-6LSPHKJ7.js

@@ -0,0 +1,88 @@
+// src/constants.ts
+var NETWORKS = {
+  base: { caip2: "eip155:8453", chainId: 8453, usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+  "base-sepolia": {
+    caip2: "eip155:84532",
+    chainId: 84532,
+    usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+  }
+};
+var USDC_DECIMALS = 6;
+var NO_REFUNDS_NOTICE = "Payments are final. Once settled on-chain the transfer cannot be reversed, and there are no refunds.";
+var DOCS_URL = "https://fatstack.net/docs/payments";
+var PAYMENT_REF_HEADER = "X-Fatstack-Payment-Ref";
+var DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+
+// src/errors.ts
+var SpendGuardError = class extends Error {
+  constructor(guard, message, detail = {}) {
+    super(message);
+    this.guard = guard;
+    this.detail = detail;
+  }
+  guard;
+  detail;
+  name = "SpendGuardError";
+};
+var NotImplementedError = class extends Error {
+  name = "NotImplementedError";
+  constructor(feature) {
+    super(`${feature} is not implemented in this build.`);
+  }
+};
+var MissingAdapterError = class extends Error {
+  name = "MissingAdapterError";
+  constructor(pkg) {
+    super(`${pkg} is not installed. Add it to use this adapter: pnpm add ${pkg}`);
+  }
+};
+
+// src/money.ts
+var UNITS_PER_USDC = 10n ** BigInt(USDC_DECIMALS);
+function parseUsdc(input) {
+  const match = /^(\d+)(?:\.(\d{1,6}))?$/.exec(input.trim());
+  if (!match) {
+    throw new RangeError(`Not a USDC amount with at most ${USDC_DECIMALS} decimals: ${input}`);
+  }
+  const whole = BigInt(match[1] ?? "0");
+  const fraction = BigInt((match[2] ?? "").padEnd(USDC_DECIMALS, "0") || "0");
+  return whole * UNITS_PER_USDC + fraction;
+}
+function formatUsdc(atomic) {
+  if (atomic < 0n) throw new RangeError("USDC amounts are never negative");
+  const whole = atomic / UNITS_PER_USDC;
+  const fraction = (atomic % UNITS_PER_USDC).toString().padStart(USDC_DECIMALS, "0");
+  const trimmed = fraction.replace(/0+$/, "");
+  return trimmed ? `${whole}.${trimmed}` : whole.toString();
+}
+var USDC_ADDRESSES = new Set(
+  Object.values(NETWORKS).map((network) => network.usdc.toLowerCase())
+);
+function quoteToUsd(quote) {
+  const decimals = USDC_ADDRESSES.has(quote.asset.toLowerCase()) ? USDC_DECIMALS : quote.decimals;
+  if (decimals === void 0 || !Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    throw new RangeError(
+      `Cannot price asset ${quote.asset}: unknown decimals. Refusing to evaluate spend guards against an unpriceable quote.`
+    );
+  }
+  if (!/^\d+$/.test(quote.amountAtomic)) {
+    throw new RangeError(`Quoted amount is not an integer atomic value: ${quote.amountAtomic}`);
+  }
+  return Number(quote.amountAtomic) / 10 ** decimals;
+}
+
+export {
+  NETWORKS,
+  USDC_DECIMALS,
+  NO_REFUNDS_NOTICE,
+  DOCS_URL,
+  PAYMENT_REF_HEADER,
+  DEFAULT_FACILITATOR_URL,
+  SpendGuardError,
+  NotImplementedError,
+  MissingAdapterError,
+  parseUsdc,
+  formatUsdc,
+  quoteToUsd
+};
+//# sourceMappingURL=chunk-6LSPHKJ7.js.map

package/dist/chunk-6LSPHKJ7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/errors.ts","../src/money.ts"],"sourcesContent":["/** Base networks in CAIP-2 form, which is what x402 v2 speaks. */\nexport const NETWORKS = {\n  base: { caip2: 'eip155:8453', chainId: 8453, usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },\n  'base-sepolia': {\n    caip2: 'eip155:84532',\n    chainId: 84532,\n    usdc: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',\n  },\n} as const;\n\nexport type NetworkName = keyof typeof NETWORKS;\n\n/** USDC is 6 decimals on Base. */\nexport const USDC_DECIMALS = 6;\n\n/**\n * Required on every 402 body and every payment-facing doc page. A payment is a direct\n * on-chain transfer between two wallets: once settled nobody, Fatstack included, can\n * reverse it.\n */\nexport const NO_REFUNDS_NOTICE =\n  'Payments are final. Once settled on-chain the transfer cannot be reversed, and there are no refunds.';\n\nexport const DOCS_URL = 'https://fatstack.net/docs/payments';\n\n/** Correlates a settled payment with the indexer's view of the on-chain transfer. */\nexport const PAYMENT_REF_HEADER = 'X-Fatstack-Payment-Ref';\n\nexport const DEFAULT_FACILITATOR_URL = 'https://x402.org/facilitator';\n","/** Names of the spend guards an agent can set. */\nexport type GuardName = 'maxPerCall' | 'maxPerHour' | 'maxPerDay' | 'allowedHosts';\n\n/**\n * Thrown before anything is signed when a call would breach a spend guard.\n *\n * Payments are final, so the only place to stop an unwanted spend is before the\n * signature exists. Every guard raises this, and it is never thrown after a payment\n * payload has been created.\n */\nexport class SpendGuardError extends Error {\n  override readonly name = 'SpendGuardError';\n\n  constructor(\n    readonly guard: GuardName,\n    message: string,\n    readonly detail: { limitUsd?: number; attemptedUsd?: number; host?: string } = {},\n  ) {\n    super(message);\n  }\n}\n\n/** Thrown by seams that are typed and reachable but deliberately not built yet. */\nexport class NotImplementedError extends Error {\n  override readonly name = 'NotImplementedError';\n\n  constructor(feature: string) {\n    super(`${feature} is not implemented in this build.`);\n  }\n}\n\n/** Thrown when an optional framework adapter is used without its package installed. */\nexport class MissingAdapterError extends Error {\n  override readonly name = 'MissingAdapterError';\n\n  constructor(pkg: string) {\n    super(`${pkg} is not installed. Add it to use this adapter: pnpm add ${pkg}`);\n  }\n}\n","import { NETWORKS, USDC_DECIMALS } from './constants.js';\n\nconst UNITS_PER_USDC = 10n ** BigInt(USDC_DECIMALS);\n\n/** \"1.25\" -> 1250000n. Rejects anything that is not a plain non-negative decimal. */\nexport function parseUsdc(input: string): bigint {\n  const match = /^(\\d+)(?:\\.(\\d{1,6}))?$/.exec(input.trim());\n  if (!match) {\n    throw new RangeError(`Not a USDC amount with at most ${USDC_DECIMALS} decimals: ${input}`);\n  }\n  const whole = BigInt(match[1] ?? '0');\n  const fraction = BigInt((match[2] ?? '').padEnd(USDC_DECIMALS, '0') || '0');\n  return whole * UNITS_PER_USDC + fraction;\n}\n\n/** 1250000n -> \"1.25\". Trailing zeros trimmed. */\nexport function formatUsdc(atomic: bigint): string {\n  if (atomic < 0n) throw new RangeError('USDC amounts are never negative');\n  const whole = atomic / UNITS_PER_USDC;\n  const fraction = (atomic % UNITS_PER_USDC).toString().padStart(USDC_DECIMALS, '0');\n  const trimmed = fraction.replace(/0+$/, '');\n  return trimmed ? `${whole}.${trimmed}` : whole.toString();\n}\n\nconst USDC_ADDRESSES = new Set(\n  Object.values(NETWORKS).map((network) => network.usdc.toLowerCase()),\n);\n\n/**\n * Converts a quoted amount to USD for guard evaluation.\n *\n * Fails closed: if the asset is not a USDC contract we recognise and the quote carries no\n * usable `decimals`, this throws rather than guessing. Guessing here would let an\n * unrecognised token slip past a spend cap, and the payment is irreversible.\n */\nexport function quoteToUsd(quote: {\n  amountAtomic: string;\n  asset: string;\n  decimals?: number | undefined;\n}): number {\n  const decimals = USDC_ADDRESSES.has(quote.asset.toLowerCase()) ? USDC_DECIMALS : quote.decimals;\n\n  if (decimals === undefined || !Number.isInteger(decimals) || decimals < 0 || decimals > 36) {\n    throw new RangeError(\n      `Cannot price asset ${quote.asset}: unknown decimals. Refusing to evaluate spend guards against an unpriceable quote.`,\n    );\n  }\n\n  if (!/^\\d+$/.test(quote.amountAtomic)) {\n    throw new RangeError(`Quoted amount is not an integer atomic value: ${quote.amountAtomic}`);\n  }\n\n  return Number(quote.amountAtomic) / 10 ** decimals;\n}\n"],"mappings":";AACO,IAAM,WAAW;AAAA,EACtB,MAAM,EAAE,OAAO,eAAe,SAAS,MAAM,MAAM,6CAA6C;AAAA,EAChG,gBAAgB;AAAA,IACd,OAAO;AAAA,IACP,SAAS;AAAA,IACT,MAAM;AAAA,EACR;AACF;AAKO,IAAM,gBAAgB;AAOtB,IAAM,oBACX;AAEK,IAAM,WAAW;AAGjB,IAAM,qBAAqB;AAE3B,IAAM,0BAA0B;;;AClBhC,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAGzC,YACW,OACT,SACS,SAAsE,CAAC,GAChF;AACA,UAAM,OAAO;AAJJ;AAEA;AAAA,EAGX;AAAA,EALW;AAAA,EAEA;AAAA,EALO,OAAO;AAS3B;AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC3B,OAAO;AAAA,EAEzB,YAAY,SAAiB;AAC3B,UAAM,GAAG,OAAO,oCAAoC;AAAA,EACtD;AACF;AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC3B,OAAO;AAAA,EAEzB,YAAY,KAAa;AACvB,UAAM,GAAG,GAAG,2DAA2D,GAAG,EAAE;AAAA,EAC9E;AACF;;;ACpCA,IAAM,iBAAiB,OAAO,OAAO,aAAa;AAG3C,SAAS,UAAU,OAAuB;AAC/C,QAAM,QAAQ,0BAA0B,KAAK,MAAM,KAAK,CAAC;AACzD,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,WAAW,kCAAkC,aAAa,cAAc,KAAK,EAAE;AAAA,EAC3F;AACA,QAAM,QAAQ,OAAO,MAAM,CAAC,KAAK,GAAG;AACpC,QAAM,WAAW,QAAQ,MAAM,CAAC,KAAK,IAAI,OAAO,eAAe,GAAG,KAAK,GAAG;AAC1E,SAAO,QAAQ,iBAAiB;AAClC;AAGO,SAAS,WAAW,QAAwB;AACjD,MAAI,SAAS,GAAI,OAAM,IAAI,WAAW,iCAAiC;AACvE,QAAM,QAAQ,SAAS;AACvB,QAAM,YAAY,SAAS,gBAAgB,SAAS,EAAE,SAAS,eAAe,GAAG;AACjF,QAAM,UAAU,SAAS,QAAQ,OAAO,EAAE;AAC1C,SAAO,UAAU,GAAG,KAAK,IAAI,OAAO,KAAK,MAAM,SAAS;AAC1D;AAEA,IAAM,iBAAiB,IAAI;AAAA,EACzB,OAAO,OAAO,QAAQ,EAAE,IAAI,CAAC,YAAY,QAAQ,KAAK,YAAY,CAAC;AACrE;AASO,SAAS,WAAW,OAIhB;AACT,QAAM,WAAW,eAAe,IAAI,MAAM,MAAM,YAAY,CAAC,IAAI,gBAAgB,MAAM;AAEvF,MAAI,aAAa,UAAa,CAAC,OAAO,UAAU,QAAQ,KAAK,WAAW,KAAK,WAAW,IAAI;AAC1F,UAAM,IAAI;AAAA,MACR,sBAAsB,MAAM,KAAK;AAAA,IACnC;AAAA,EACF;AAEA,MAAI,CAAC,QAAQ,KAAK,MAAM,YAAY,GAAG;AACrC,UAAM,IAAI,WAAW,iDAAiD,MAAM,YAAY,EAAE;AAAA,EAC5F;AAEA,SAAO,OAAO,MAAM,YAAY,IAAI,MAAM;AAC5C;","names":[]}

package/dist/chunk-7DVR574O.js

@@ -0,0 +1,213 @@
+import {
+  DEFAULT_FACILITATOR_URL,
+  DOCS_URL,
+  MissingAdapterError,
+  NETWORKS,
+  NO_REFUNDS_NOTICE,
+  NotImplementedError,
+  PAYMENT_REF_HEADER,
+  formatUsdc,
+  parseUsdc
+} from "./chunk-6LSPHKJ7.js";
+
+// src/provider.ts
+import { decodePaymentResponseHeader } from "@x402/core/http";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { z as z2 } from "zod";
+
+// src/env.ts
+import { z } from "zod";
+var paywallEnvSchema = z.object({
+  /** Hosted facilitator (Coinbase CDP). Fatstack does not run its own. */
+  FACILITATOR_URL: z.string().url().default(DEFAULT_FACILITATOR_URL),
+  FACILITATOR_API_KEY: z.string().min(1).optional(),
+  /**
+   * `1` takes every paywalled route offline with a 503. Intended for an incident where
+   * continuing to take irreversible payments would be worse than being down.
+   */
+  KILLSWITCH: z.enum(["0", "1"]).default("0"),
+  /**
+   * direct   = agent pays the provider wallet, 0% platform fee (the launch build)
+   * splitter = reserved for the fee-splitting contract; not implemented
+   */
+  FEE_MODE: z.enum(["direct", "splitter"]).default("direct")
+});
+function readPaywallEnv(source = process.env) {
+  return paywallEnvSchema.parse({
+    FACILITATOR_URL: source.FACILITATOR_URL,
+    FACILITATOR_API_KEY: source.FACILITATOR_API_KEY,
+    KILLSWITCH: source.KILLSWITCH,
+    FEE_MODE: source.FEE_MODE
+  });
+}
+
+// src/fee-mode.ts
+function resolvePayee(mode, providerWallet) {
+  switch (mode) {
+    case "direct":
+      return { payTo: providerWallet, feeBps: 0 };
+    case "splitter":
+      throw new NotImplementedError(
+        "FEE_MODE=splitter (no splitter contract ships in the launch build)"
+      );
+  }
+}
+
+// src/provider.ts
+var optionsSchema = z2.object({
+  /** Price per call in USD, as a decimal string: "0.002". */
+  price: z2.string().regex(/^\d+(?:\.\d{1,6})?$/, "price must be USD with at most 6 decimals"),
+  /** The provider's own wallet. Under FEE_MODE=direct this is the sole payee. */
+  wallet: z2.string().regex(/^0x[0-9a-fA-F]{40}$/, "wallet must be a 20-byte address"),
+  toolId: z2.string().min(1).max(128),
+  network: z2.enum(["base", "base-sepolia"]).default("base"),
+  description: z2.string().optional(),
+  docsUrl: z2.string().url().default(DOCS_URL),
+  mimeType: z2.string().default("application/json"),
+  maxTimeoutSeconds: z2.number().int().positive().default(60)
+});
+var KILLSWITCH_BODY = {
+  error: "service_unavailable",
+  message: "This tool is temporarily disabled by its operator (KILLSWITCH). No payment was taken. Try again later."
+};
+function paywall(options) {
+  const config = optionsSchema.parse(options);
+  const env = readPaywallEnv(options.env);
+  const network = NETWORKS[config.network];
+  const { payTo } = resolvePayee(env.FEE_MODE, config.wallet);
+  const amountAtomic = parseUsdc(config.price).toString();
+  const priceUsdc = formatUsdc(parseUsdc(config.price));
+  const unpaidBody = {
+    error: "payment_required",
+    tool: config.toolId,
+    price: {
+      usdc: priceUsdc,
+      amountAtomic,
+      asset: network.usdc,
+      network: network.caip2
+    },
+    payTo,
+    terms: { refundable: false, notice: NO_REFUNDS_NOTICE },
+    docs: config.docsUrl,
+    message: `This call costs ${priceUsdc} USDC on ${config.network}, paid directly to the provider. ${NO_REFUNDS_NOTICE} See ${config.docsUrl}`
+  };
+  const routeConfig = {
+    accepts: {
+      scheme: "exact",
+      network: network.caip2,
+      payTo,
+      // An explicit asset+amount pins USDC and the exact atomic amount, rather than
+      // leaving the quote to a price feed.
+      price: { asset: network.usdc, amount: amountAtomic },
+      maxTimeoutSeconds: config.maxTimeoutSeconds
+    },
+    description: config.description ?? `Fatstack tool ${config.toolId}`,
+    mimeType: config.mimeType,
+    unpaidResponseBody: () => ({ contentType: "application/json", body: unpaidBody })
+  };
+  const facilitator = options.facilitator ?? new HTTPFacilitatorClient({
+    url: env.FACILITATOR_URL,
+    ...env.FACILITATOR_API_KEY ? {
+      createAuthHeaders: async () => ({
+        verify: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` },
+        settle: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` },
+        supported: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` }
+      })
+    } : {}
+  });
+  const server = new x402ResourceServer(facilitator).register(network.caip2, new ExactEvmScheme());
+  const killed = env.KILLSWITCH === "1";
+  function paymentRef(paymentResponseHeader) {
+    if (!paymentResponseHeader) return null;
+    try {
+      const settled = decodePaymentResponseHeader(paymentResponseHeader);
+      const transaction = settled.transaction;
+      return transaction ? `${config.toolId}:${network.caip2}:${transaction}` : null;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    routeConfig,
+    payTo,
+    hono() {
+      let cached;
+      return async (c, next) => {
+        if (killed) return c.json(KILLSWITCH_BODY, 503);
+        if (!cached) {
+          const mod = await importOptional("@x402/hono");
+          cached = mod.paymentMiddleware(routeConfig, server);
+        }
+        const middleware = cached;
+        const result = await middleware(c, next);
+        const carrier = result instanceof Response ? result : c.res;
+        const ref = paymentRef(carrier?.headers?.get("x-payment-response"));
+        if (ref) carrier.headers.set(PAYMENT_REF_HEADER, ref);
+        return result;
+      };
+    },
+    express() {
+      let cached;
+      return async (req, res, next) => {
+        const response = res;
+        if (killed) {
+          response.status(503).json(KILLSWITCH_BODY);
+          return;
+        }
+        if (!cached) {
+          const mod = await importOptional("@x402/express");
+          cached = mod.paymentMiddleware(routeConfig, server);
+        }
+        const originalSetHeader = response.setHeader.bind(response);
+        response.setHeader = (name, value) => {
+          const out = originalSetHeader(name, value);
+          if (String(name).toLowerCase() === "x-payment-response") {
+            const ref = paymentRef(String(value));
+            if (ref) originalSetHeader(PAYMENT_REF_HEADER, ref);
+          }
+          return out;
+        };
+        const middleware = cached;
+        await middleware(req, res, next);
+      };
+    },
+    next(handler) {
+      let cached;
+      return async (request) => {
+        if (killed) {
+          return Response.json(KILLSWITCH_BODY, { status: 503 });
+        }
+        if (!cached) {
+          const mod = await importOptional("@x402/next");
+          cached = mod.withX402(handler, routeConfig, server);
+        }
+        const wrapped = cached;
+        const result = await wrapped(request);
+        if (result instanceof Response) {
+          const ref = paymentRef(result.headers.get("x-payment-response"));
+          if (ref) result.headers.set(PAYMENT_REF_HEADER, ref);
+        }
+        return result;
+      };
+    }
+  };
+}
+async function importOptional(specifier) {
+  try {
+    return await import(
+      /* @vite-ignore */
+      specifier
+    );
+  } catch {
+    throw new MissingAdapterError(specifier);
+  }
+}
+
+export {
+  resolvePayee,
+  paywallEnvSchema,
+  readPaywallEnv,
+  paywall
+};
+//# sourceMappingURL=chunk-7DVR574O.js.map

package/dist/chunk-7DVR574O.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider.ts","../src/env.ts","../src/fee-mode.ts"],"sourcesContent":["import { decodePaymentResponseHeader } from '@x402/core/http';\nimport { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';\nimport type { FacilitatorClient, RouteConfig } from '@x402/core/server';\nimport { ExactEvmScheme } from '@x402/evm/exact/server';\nimport { z } from 'zod';\n\nimport { DOCS_URL, NETWORKS, NO_REFUNDS_NOTICE, PAYMENT_REF_HEADER } from './constants.js';\nimport type { NetworkName } from './constants.js';\nimport { readPaywallEnv } from './env.js';\nimport { MissingAdapterError } from './errors.js';\nimport { resolvePayee } from './fee-mode.js';\nimport { formatUsdc, parseUsdc } from './money.js';\n\nconst optionsSchema = z.object({\n  /** Price per call in USD, as a decimal string: \"0.002\". */\n  price: z.string().regex(/^\\d+(?:\\.\\d{1,6})?$/, 'price must be USD with at most 6 decimals'),\n  /** The provider's own wallet. Under FEE_MODE=direct this is the sole payee. */\n  wallet: z.string().regex(/^0x[0-9a-fA-F]{40}$/, 'wallet must be a 20-byte address'),\n  toolId: z.string().min(1).max(128),\n  network: z.enum(['base', 'base-sepolia']).default('base'),\n  description: z.string().optional(),\n  docsUrl: z.string().url().default(DOCS_URL),\n  mimeType: z.string().default('application/json'),\n  maxTimeoutSeconds: z.number().int().positive().default(60),\n});\n\nexport interface PaywallOptions extends z.input<typeof optionsSchema> {\n  /** Defaults to process.env. */\n  env?: Record<string, string | undefined>;\n  /** Injects a facilitator instead of building an HTTP one. Used by tests. */\n  facilitator?: FacilitatorClient;\n}\n\n/** The 402 body an agent reads before deciding to pay. */\nexport interface UnpaidBody {\n  error: 'payment_required';\n  tool: string;\n  price: { usdc: string; amountAtomic: string; asset: string; network: string };\n  payTo: string;\n  terms: { refundable: false; notice: string };\n  docs: string;\n  message: string;\n}\n\n/** Structurally compatible with Hono's `MiddlewareHandler`, without importing hono. */\nexport interface HonoContextLike {\n  json: (body: unknown, status?: number) => Response;\n  res: Response;\n  req: { raw: Request };\n}\nexport type HonoMiddleware = (\n  c: HonoContextLike,\n  next: () => Promise<void>,\n) => Promise<Response | void>;\n\n/** Structurally compatible with an Express request handler. */\nexport interface ExpressResponseLike {\n  status: (code: number) => { json: (body: unknown) => void };\n  setHeader: (name: string, value: string | number | readonly string[]) => unknown;\n}\nexport type ExpressMiddleware = (\n  req: unknown,\n  res: ExpressResponseLike,\n  next: (err?: unknown) => void,\n) => Promise<void>;\n\nexport interface Paywall {\n  /** Hono middleware. Requires @x402/hono. */\n  hono(): HonoMiddleware;\n  /** Express middleware. Requires @x402/express. */\n  express(): ExpressMiddleware;\n  /** Wraps a Next.js route handler. Requires @x402/next (which needs Next >= 16.2.6). */\n  next<T>(handler: (request: never) => Promise<T>): (request: never) => Promise<T>;\n  /** The x402 route config, for advanced use with the official adapters directly. */\n  routeConfig: RouteConfig;\n  /** Resolved payee. Always the provider wallet while FEE_MODE=direct. */\n  payTo: string;\n}\n\n/** Minimal shapes of the optional adapter packages, so their types are not required. */\ninterface HonoAdapterModule {\n  paymentMiddleware: (routes: RouteConfig, server: x402ResourceServer) => unknown;\n}\ninterface ExpressAdapterModule {\n  paymentMiddleware: (routes: RouteConfig, server: x402ResourceServer) => unknown;\n}\ninterface NextAdapterModule {\n  withX402: (handler: unknown, routeConfig: RouteConfig, server: x402ResourceServer) => unknown;\n}\n\nconst KILLSWITCH_BODY = {\n  error: 'service_unavailable',\n  message:\n    'This tool is temporarily disabled by its operator (KILLSWITCH). No payment was taken. Try again later.',\n} as const;\n\n/**\n * Paywalls a route with x402: USDC on Base, paid directly to the provider's wallet.\n *\n * Verification and settlement are delegated to the official x402 packages against the\n * hosted facilitator — this module does not sign or verify anything itself.\n *\n * Throws immediately when FEE_MODE=splitter: there is no splitter contract in this build,\n * and silently falling back to `direct` would pay the wrong party.\n */\nexport function paywall(options: PaywallOptions): Paywall {\n  const config = optionsSchema.parse(options);\n  const env = readPaywallEnv(options.env);\n  const network = NETWORKS[config.network as NetworkName];\n\n  // Throws for FEE_MODE=splitter, at construction time rather than mid-request.\n  const { payTo } = resolvePayee(env.FEE_MODE, config.wallet);\n\n  const amountAtomic = parseUsdc(config.price).toString();\n  const priceUsdc = formatUsdc(parseUsdc(config.price));\n\n  const unpaidBody: UnpaidBody = {\n    error: 'payment_required',\n    tool: config.toolId,\n    price: {\n      usdc: priceUsdc,\n      amountAtomic,\n      asset: network.usdc,\n      network: network.caip2,\n    },\n    payTo,\n    terms: { refundable: false, notice: NO_REFUNDS_NOTICE },\n    docs: config.docsUrl,\n    message: `This call costs ${priceUsdc} USDC on ${config.network}, paid directly to the provider. ${NO_REFUNDS_NOTICE} See ${config.docsUrl}`,\n  };\n\n  const routeConfig: RouteConfig = {\n    accepts: {\n      scheme: 'exact',\n      network: network.caip2,\n      payTo,\n      // An explicit asset+amount pins USDC and the exact atomic amount, rather than\n      // leaving the quote to a price feed.\n      price: { asset: network.usdc, amount: amountAtomic },\n      maxTimeoutSeconds: config.maxTimeoutSeconds,\n    },\n    description: config.description ?? `Fatstack tool ${config.toolId}`,\n    mimeType: config.mimeType,\n    unpaidResponseBody: () => ({ contentType: 'application/json', body: unpaidBody }),\n  };\n\n  const facilitator: FacilitatorClient =\n    options.facilitator ??\n    new HTTPFacilitatorClient({\n      url: env.FACILITATOR_URL,\n      ...(env.FACILITATOR_API_KEY\n        ? {\n            createAuthHeaders: async () => ({\n              verify: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` },\n              settle: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` },\n              supported: { authorization: `Bearer ${env.FACILITATOR_API_KEY}` },\n            }),\n          }\n        : {}),\n    });\n\n  const server = new x402ResourceServer(facilitator).register(network.caip2, new ExactEvmScheme());\n\n  const killed = env.KILLSWITCH === '1';\n\n  /** Derives the indexing reference from the settlement receipt the adapter emitted. */\n  function paymentRef(paymentResponseHeader: string | null | undefined): string | null {\n    if (!paymentResponseHeader) return null;\n    try {\n      const settled = decodePaymentResponseHeader(paymentResponseHeader);\n      const transaction = (settled as { transaction?: string }).transaction;\n      return transaction ? `${config.toolId}:${network.caip2}:${transaction}` : null;\n    } catch {\n      return null;\n    }\n  }\n\n  return {\n    routeConfig,\n    payTo,\n\n    hono(): HonoMiddleware {\n      let cached: unknown;\n      return async (c, next) => {\n        if (killed) return c.json(KILLSWITCH_BODY, 503);\n\n        if (!cached) {\n          const mod = await importOptional<HonoAdapterModule>('@x402/hono');\n          cached = mod.paymentMiddleware(routeConfig, server);\n        }\n        const middleware = cached as (\n          ctx: HonoContextLike,\n          n: () => Promise<void>,\n        ) => Promise<Response | void>;\n        const result = await middleware(c, next);\n\n        // c.res carries the response Hono will send, whether the middleware set it or\n        // the downstream handler did.\n        const carrier = result instanceof Response ? result : c.res;\n        const ref = paymentRef(carrier?.headers?.get('x-payment-response'));\n        if (ref) carrier.headers.set(PAYMENT_REF_HEADER, ref);\n        return result;\n      };\n    },\n\n    express(): ExpressMiddleware {\n      let cached: unknown;\n      return async (req, res, next) => {\n        const response = res;\n        if (killed) {\n          response.status(503).json(KILLSWITCH_BODY);\n          return;\n        }\n\n        if (!cached) {\n          const mod = await importOptional<ExpressAdapterModule>('@x402/express');\n          cached = mod.paymentMiddleware(routeConfig, server);\n        }\n\n        // Headers must be attached before the response flushes, so mirror the settlement\n        // receipt onto the ref header the moment the adapter sets it.\n        const originalSetHeader = response.setHeader.bind(response);\n        response.setHeader = (name, value) => {\n          const out = originalSetHeader(name, value);\n          if (String(name).toLowerCase() === 'x-payment-response') {\n            const ref = paymentRef(String(value));\n            if (ref) originalSetHeader(PAYMENT_REF_HEADER, ref);\n          }\n          return out;\n        };\n\n        const middleware = cached as (\n          q: unknown,\n          s: unknown,\n          n: (err?: unknown) => void,\n        ) => Promise<void>;\n        await middleware(req, res, next);\n      };\n    },\n\n    next<T>(handler: (request: never) => Promise<T>) {\n      let cached: unknown;\n      return async (request: never): Promise<T> => {\n        if (killed) {\n          return Response.json(KILLSWITCH_BODY, { status: 503 }) as T;\n        }\n\n        if (!cached) {\n          const mod = await importOptional<NextAdapterModule>('@x402/next');\n          cached = mod.withX402(handler as never, routeConfig, server);\n        }\n        const wrapped = cached as (r: never) => Promise<T>;\n        const result = await wrapped(request);\n\n        if (result instanceof Response) {\n          const ref = paymentRef(result.headers.get('x-payment-response'));\n          if (ref) result.headers.set(PAYMENT_REF_HEADER, ref);\n        }\n        return result;\n      };\n    },\n  };\n}\n\nasync function importOptional<T>(specifier: string): Promise<T> {\n  try {\n    return (await import(/* @vite-ignore */ specifier)) as T;\n  } catch {\n    throw new MissingAdapterError(specifier);\n  }\n}\n\nexport type { FacilitatorClient, RouteConfig } from '@x402/core/server';\n","import { z } from 'zod';\n\nimport { DEFAULT_FACILITATOR_URL } from './constants.js';\n\n/**\n * Environment the paywall reads. Parsed lazily inside `paywall()`, never at module load,\n * so importing this package never throws in a build step.\n */\nexport const paywallEnvSchema = z.object({\n  /** Hosted facilitator (Coinbase CDP). Fatstack does not run its own. */\n  FACILITATOR_URL: z.string().url().default(DEFAULT_FACILITATOR_URL),\n  FACILITATOR_API_KEY: z.string().min(1).optional(),\n  /**\n   * `1` takes every paywalled route offline with a 503. Intended for an incident where\n   * continuing to take irreversible payments would be worse than being down.\n   */\n  KILLSWITCH: z.enum(['0', '1']).default('0'),\n  /**\n   * direct   = agent pays the provider wallet, 0% platform fee (the launch build)\n   * splitter = reserved for the fee-splitting contract; not implemented\n   */\n  FEE_MODE: z.enum(['direct', 'splitter']).default('direct'),\n});\n\nexport type PaywallEnv = z.infer<typeof paywallEnvSchema>;\n\nexport function readPaywallEnv(\n  source: Record<string, string | undefined> = process.env,\n): PaywallEnv {\n  return paywallEnvSchema.parse({\n    FACILITATOR_URL: source.FACILITATOR_URL,\n    FACILITATOR_API_KEY: source.FACILITATOR_API_KEY,\n    KILLSWITCH: source.KILLSWITCH,\n    FEE_MODE: source.FEE_MODE,\n  });\n}\n","import { NotImplementedError } from './errors.js';\n\nexport type FeeMode = 'direct' | 'splitter';\n\nexport interface PayeeResolution {\n  /** The single address that receives the transfer. */\n  payTo: string;\n  /** Platform fee in basis points. Always 0 while FEE_MODE=direct. */\n  feeBps: number;\n}\n\n/**\n * Resolves who is paid for a call. Under `direct` this is always, and only, the\n * provider's own wallet — the platform is never a payee and never custodies funds.\n *\n * `splitter` is a reserved seam for the fee-splitting contract. It is typed and reachable\n * so the shape is settled, but it throws: there is no splitter contract in this build.\n */\nexport function resolvePayee(mode: FeeMode, providerWallet: string): PayeeResolution {\n  switch (mode) {\n    case 'direct':\n      return { payTo: providerWallet, feeBps: 0 };\n    case 'splitter':\n      throw new NotImplementedError(\n        'FEE_MODE=splitter (no splitter contract ships in the launch build)',\n      );\n  }\n}\n"],"mappings":"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","names":["z","z"]}

package/dist/chunk-HCN75CTX.js

@@ -0,0 +1,144 @@
+import {
+  NETWORKS,
+  SpendGuardError,
+  quoteToUsd
+} from "./chunk-6LSPHKJ7.js";
+
+// src/client.ts
+import { x402Client } from "@x402/core/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+
+// src/store.ts
+function createMemorySpendStore(retentionMs = 24 * 60 * 60 * 1e3) {
+  let entries = [];
+  return {
+    record(entry) {
+      entries.push(entry);
+      const cutoff = entry.at - retentionMs;
+      if (entries.length > 64) entries = entries.filter((e) => e.at >= cutoff);
+    },
+    totalSince(sinceMs) {
+      let total = 0;
+      for (const entry of entries) if (entry.at >= sinceMs) total += entry.usd;
+      return total;
+    }
+  };
+}
+
+// src/client.ts
+var HOUR_MS = 60 * 60 * 1e3;
+var DAY_MS = 24 * HOUR_MS;
+function hostOf(input) {
+  try {
+    const raw = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    return new URL(raw).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+function hostAllowed(host, allowed) {
+  return allowed.some((entry) => {
+    const candidate = entry.trim().toLowerCase().replace(/^\*\./, "");
+    return host === candidate || host.endsWith(`.${candidate}`);
+  });
+}
+async function evaluateGuards(quoteUsd, guards, store, now) {
+  if (guards.maxPerCall !== void 0 && quoteUsd > guards.maxPerCall) {
+    throw new SpendGuardError(
+      "maxPerCall",
+      `Call costs $${quoteUsd} which exceeds the maxPerCall limit of $${guards.maxPerCall}`,
+      { limitUsd: guards.maxPerCall, attemptedUsd: quoteUsd }
+    );
+  }
+  if (guards.maxPerHour !== void 0) {
+    const spent = await store.totalSince(now - HOUR_MS);
+    if (spent + quoteUsd > guards.maxPerHour) {
+      throw new SpendGuardError(
+        "maxPerHour",
+        `Call costs $${quoteUsd} and $${spent} was already spent this hour, exceeding the maxPerHour limit of $${guards.maxPerHour}`,
+        { limitUsd: guards.maxPerHour, attemptedUsd: spent + quoteUsd }
+      );
+    }
+  }
+  if (guards.maxPerDay !== void 0) {
+    const spent = await store.totalSince(now - DAY_MS);
+    if (spent + quoteUsd > guards.maxPerDay) {
+      throw new SpendGuardError(
+        "maxPerDay",
+        `Call costs $${quoteUsd} and $${spent} was already spent today, exceeding the maxPerDay limit of $${guards.maxPerDay}`,
+        { limitUsd: guards.maxPerDay, attemptedUsd: spent + quoteUsd }
+      );
+    }
+  }
+}
+function quoteUsdOf(requirements) {
+  const asRecord = requirements;
+  const amountAtomic = asRecord.maxAmountRequired ?? asRecord.amount;
+  if (!amountAtomic || !asRecord.asset) {
+    throw new RangeError("Payment requirements carry no priceable amount; refusing to pay.");
+  }
+  return quoteToUsd({
+    amountAtomic,
+    asset: asRecord.asset,
+    decimals: asRecord.extra?.decimals
+  });
+}
+async function payFetch(url, init, options) {
+  const guards = options.guards ?? {};
+  const store = options.store ?? createMemorySpendStore();
+  const now = options.now ?? Date.now;
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const networks = options.networks ?? ["base"];
+  if (guards.allowedHosts) {
+    const host = hostOf(url);
+    if (!host || !hostAllowed(host, guards.allowedHosts)) {
+      throw new SpendGuardError(
+        "allowedHosts",
+        `Host ${host ?? "<unparseable>"} is not in allowedHosts`,
+        { host: host ?? void 0 }
+      );
+    }
+  }
+  let quotedUsd = null;
+  const client = new x402Client((_version, requirements) => {
+    const affordable = requirements.filter((requirement) => {
+      const usd = quoteUsdOf(requirement);
+      return guards.maxPerCall === void 0 || usd <= guards.maxPerCall;
+    });
+    const chosen = (affordable.length > 0 ? affordable : requirements)[0];
+    if (!chosen) throw new RangeError("Resource offered no payment requirements");
+    quotedUsd = quoteUsdOf(chosen);
+    return chosen;
+  });
+  for (const name of networks) {
+    client.register(NETWORKS[name].caip2, new ExactEvmScheme(options.wallet));
+  }
+  const guarded = async (input, requestInit) => {
+    const response2 = await baseFetch(input, requestInit);
+    if (response2.status !== 402) return response2;
+    const body = await response2.clone().json().catch(() => null);
+    const accepts = body?.accepts;
+    if (Array.isArray(accepts) && accepts.length > 0) {
+      const cheapest = accepts.map((requirement) => quoteUsdOf(requirement)).sort((a, b) => a - b)[0];
+      if (cheapest !== void 0) {
+        await evaluateGuards(cheapest, guards, store, now());
+      }
+    }
+    return response2;
+  };
+  const paying = wrapFetchWithPayment(guarded, client);
+  const response = await paying(url, init);
+  if (response.headers.get("x-payment-response") && quotedUsd !== null) {
+    await store.record({ at: now(), usd: quotedUsd });
+  }
+  return response;
+}
+
+export {
+  createMemorySpendStore,
+  evaluateGuards,
+  quoteUsdOf,
+  payFetch
+};
+//# sourceMappingURL=chunk-HCN75CTX.js.map

package/dist/chunk-HCN75CTX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/store.ts"],"sourcesContent":["import { x402Client } from '@x402/core/client';\nimport type { PaymentRequirements } from '@x402/core/types';\nimport { ExactEvmScheme } from '@x402/evm/exact/client';\nimport { wrapFetchWithPayment } from '@x402/fetch';\n\nimport { NETWORKS, PAYMENT_REF_HEADER } from './constants.js';\nimport type { NetworkName } from './constants.js';\nimport { SpendGuardError } from './errors.js';\nimport { quoteToUsd } from './money.js';\nimport { createMemorySpendStore } from './store.js';\nimport type { SpendStore } from './store.js';\n\n/** The signer the official EVM scheme expects: address + signTypedData, no key handling. */\nexport type EvmWallet = ConstructorParameters<typeof ExactEvmScheme>[0];\n\nexport interface SpendGuards {\n  /** Hard USD ceiling for a single call. */\n  maxPerCall?: number;\n  /** Rolling 60-minute USD ceiling. */\n  maxPerHour?: number;\n  /** Rolling 24-hour USD ceiling. */\n  maxPerDay?: number;\n  /** Hostnames this agent may pay. Checked before any network call. */\n  allowedHosts?: string[];\n}\n\nexport interface PayFetchOptions {\n  wallet: EvmWallet;\n  guards?: SpendGuards;\n  /** Defaults to a process-local in-memory store. */\n  store?: SpendStore;\n  networks?: NetworkName[];\n  fetch?: typeof globalThis.fetch;\n  now?: () => number;\n}\n\nconst HOUR_MS = 60 * 60 * 1000;\nconst DAY_MS = 24 * HOUR_MS;\n\nfunction hostOf(input: RequestInfo | URL): string | null {\n  try {\n    const raw =\n      typeof input === 'string'\n        ? input\n        : input instanceof URL\n          ? input.toString()\n          : (input as Request).url;\n    return new URL(raw).hostname.toLowerCase();\n  } catch {\n    return null;\n  }\n}\n\n/** `example.com` in allowedHosts also authorises `tool.example.com`. */\nfunction hostAllowed(host: string, allowed: readonly string[]): boolean {\n  return allowed.some((entry) => {\n    const candidate = entry.trim().toLowerCase().replace(/^\\*\\./, '');\n    return host === candidate || host.endsWith(`.${candidate}`);\n  });\n}\n\n/**\n * Checks every guard against a quote. Returns the USD value if the call may proceed,\n * throws SpendGuardError otherwise. Called before a payment payload exists.\n */\nexport async function evaluateGuards(\n  quoteUsd: number,\n  guards: SpendGuards,\n  store: SpendStore,\n  now: number,\n): Promise<void> {\n  if (guards.maxPerCall !== undefined && quoteUsd > guards.maxPerCall) {\n    throw new SpendGuardError(\n      'maxPerCall',\n      `Call costs $${quoteUsd} which exceeds the maxPerCall limit of $${guards.maxPerCall}`,\n      { limitUsd: guards.maxPerCall, attemptedUsd: quoteUsd },\n    );\n  }\n\n  if (guards.maxPerHour !== undefined) {\n    const spent = await store.totalSince(now - HOUR_MS);\n    if (spent + quoteUsd > guards.maxPerHour) {\n      throw new SpendGuardError(\n        'maxPerHour',\n        `Call costs $${quoteUsd} and $${spent} was already spent this hour, exceeding the maxPerHour limit of $${guards.maxPerHour}`,\n        { limitUsd: guards.maxPerHour, attemptedUsd: spent + quoteUsd },\n      );\n    }\n  }\n\n  if (guards.maxPerDay !== undefined) {\n    const spent = await store.totalSince(now - DAY_MS);\n    if (spent + quoteUsd > guards.maxPerDay) {\n      throw new SpendGuardError(\n        'maxPerDay',\n        `Call costs $${quoteUsd} and $${spent} was already spent today, exceeding the maxPerDay limit of $${guards.maxPerDay}`,\n        { limitUsd: guards.maxPerDay, attemptedUsd: spent + quoteUsd },\n      );\n    }\n  }\n}\n\n/** Reads the quoted amount out of x402 payment requirements. */\ninterface PriceableRequirement {\n  maxAmountRequired?: string;\n  amount?: string;\n  asset?: string;\n  extra?: { decimals?: number };\n}\n\nexport function quoteUsdOf(requirements: PaymentRequirements): number {\n  const asRecord: PriceableRequirement = requirements;\n  const amountAtomic = asRecord.maxAmountRequired ?? asRecord.amount;\n  if (!amountAtomic || !asRecord.asset) {\n    throw new RangeError('Payment requirements carry no priceable amount; refusing to pay.');\n  }\n  return quoteToUsd({\n    amountAtomic,\n    asset: asRecord.asset,\n    decimals: asRecord.extra?.decimals,\n  });\n}\n\n/**\n * A `fetch` that pays for 402 responses, under spend guards.\n *\n * The 402 handling, signing and retry are the official x402 packages' work. What this adds\n * is refusal: guards are evaluated inside the payment-policy hook, which runs after the\n * quote is known and before any payload is signed, so exceeding a guard throws\n * SpendGuardError with nothing signed and nothing spent.\n */\nexport async function payFetch(\n  url: RequestInfo | URL,\n  init: RequestInit | undefined,\n  options: PayFetchOptions,\n): Promise<Response> {\n  const guards = options.guards ?? {};\n  const store = options.store ?? createMemorySpendStore();\n  const now = options.now ?? Date.now;\n  const baseFetch = options.fetch ?? globalThis.fetch;\n  const networks = options.networks ?? (['base'] as NetworkName[]);\n\n  // Host allowlist is checked first: an unauthorised host should cost no request at all.\n  if (guards.allowedHosts) {\n    const host = hostOf(url);\n    if (!host || !hostAllowed(host, guards.allowedHosts)) {\n      throw new SpendGuardError(\n        'allowedHosts',\n        `Host ${host ?? '<unparseable>'} is not in allowedHosts`,\n        { host: host ?? undefined },\n      );\n    }\n  }\n\n  let quotedUsd: number | null = null;\n\n  const client = new x402Client((_version, requirements) => {\n    // Runs before the payment payload is created. Throwing here means no signature.\n    const affordable = requirements.filter((requirement) => {\n      const usd = quoteUsdOf(requirement);\n      return guards.maxPerCall === undefined || usd <= guards.maxPerCall;\n    });\n\n    const chosen = (affordable.length > 0 ? affordable : requirements)[0];\n    if (!chosen) throw new RangeError('Resource offered no payment requirements');\n\n    quotedUsd = quoteUsdOf(chosen);\n    return chosen;\n  });\n\n  for (const name of networks) {\n    client.register(NETWORKS[name].caip2, new ExactEvmScheme(options.wallet));\n  }\n\n  const guarded: typeof globalThis.fetch = async (input, requestInit) => {\n    const response = await baseFetch(input, requestInit);\n    if (response.status !== 402) return response;\n\n    // Peek at the quote and apply guards before the wrapper signs anything.\n    const body = await response\n      .clone()\n      .json()\n      .catch(() => null);\n    const accepts = (body as { accepts?: PaymentRequirements[] } | null)?.accepts;\n    if (Array.isArray(accepts) && accepts.length > 0) {\n      const cheapest = accepts\n        .map((requirement) => quoteUsdOf(requirement))\n        .sort((a, b) => a - b)[0];\n      if (cheapest !== undefined) {\n        await evaluateGuards(cheapest, guards, store, now());\n      }\n    }\n    return response;\n  };\n\n  const paying = wrapFetchWithPayment(guarded, client);\n  const response = await paying(url as RequestInfo, init);\n\n  // Record the spend only once a payment actually settled.\n  if (response.headers.get('x-payment-response') && quotedUsd !== null) {\n    await store.record({ at: now(), usd: quotedUsd });\n  }\n\n  return response;\n}\n\nexport { PAYMENT_REF_HEADER };\n","/** One recorded spend, in USD, at a wall-clock millisecond. */\nexport interface SpendRecord {\n  at: number;\n  usd: number;\n}\n\n/**\n * Where rolling spend totals live. The default is in-memory and per-process; swap in a\n * shared implementation (Redis, Durable Object, Postgres) when an agent runs as more\n * than one process, otherwise each process enforces its own separate budget.\n */\nexport interface SpendStore {\n  record(entry: SpendRecord): Promise<void> | void;\n  /** Total USD recorded at or after `sinceMs`. */\n  totalSince(sinceMs: number): Promise<number> | number;\n}\n\n/** Process-local store. Entries older than the longest window are dropped on write. */\nexport function createMemorySpendStore(retentionMs = 24 * 60 * 60 * 1000): SpendStore {\n  let entries: SpendRecord[] = [];\n\n  return {\n    record(entry) {\n      entries.push(entry);\n      const cutoff = entry.at - retentionMs;\n      if (entries.length > 64) entries = entries.filter((e) => e.at >= cutoff);\n    },\n    totalSince(sinceMs) {\n      let total = 0;\n      for (const entry of entries) if (entry.at >= sinceMs) total += entry.usd;\n      return total;\n    },\n  };\n}\n"],"mappings":"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","names":["response"]}