x402-seatbelt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gmahar82-stack
+
+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,69 @@
+# x402-seatbelt
+
+**A seatbelt for AI agents that pay with [x402](https://www.x402.org).** Spending budgets, per-payment caps, an emergency stop and an optional **Pay Safe** check, applied to every payment **before it leaves your machine**.
+
+Agents that pay for APIs can overspend, pay a service that's down, get charged more than the listed price, or pay a tampered wallet. x402-seatbelt wraps `fetch`, reads each signed payment as it's about to go out, and blocks it when it crosses a line you set. A blocked payment is never delivered, so **nothing is paid**.
+
+```ts
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { createSeatbelt } from "x402-seatbelt";
+
+const seatbelt = createSeatbelt({
+  maxTotalUsd: 2.0,      // budget for all payments
+  maxPaymentUsd: 0.05,   // no single payment above 5 cents
+  paySafe: true,         // optional: check each payment with Pay Safe first
+});
+
+const fetchWithPayment = wrapFetchWithPayment(seatbelt.wrap(fetch), client);
+
+await fetchWithPayment("https://api.example.com/paid-endpoint");
+console.log(seatbelt.report()); // { payments: 1, spentUsd: 0.01, blocked: 0, ... }
+```
+
+The seatbelt goes **inside** the x402 client (`wrap(fetch)` is passed to `wrapFetchWithPayment`), so it sees the paid retry that the client sends.
+
+## Install
+
+```bash
+npm install x402-seatbelt
+```
+
+No dependencies. It works anywhere `fetch` does: Node 18+, Deno, Bun, Cloudflare Workers and browsers. It ships as both ESM and CommonJS, with types.
+
+## Options
+
+| Option | What happens |
+|---|---|
+| `maxTotalUsd` | A payment that would push the total over the budget is never sent. Parallel payments reserve their amount, so they can't overshoot together. |
+| `maxPaymentUsd` | Any single payment above the cap is blocked. Payments in other assets are blocked too, because their dollar value is unknown. |
+| `maxPayments` | Blocks payments after this many. |
+| `paySafe` | Checks each payment with Pay Safe (see below). Off by default. |
+| `paySafeBlock` | `"stop"` (default) blocks STOP answers; `"caution"` also blocks CAUTION. |
+| `paySafeFailClosed` | Blocks payments when Pay Safe can't be reached (default: let them through). |
+| `paySafeUrl`, `paySafeTimeoutMs` | Endpoint (default: the public Pay Safe) and timeout (default 8000). |
+| `onEvent` | A callback for every payment, block and Pay Safe answer. |
+
+- `seatbelt.stop()` blocks every further payment (an emergency stop).
+- `seatbelt.report()` returns payments, `spentUsd`, `pendingUsd`, blocked count, Pay Safe checks and the last 200 events.
+
+A blocked payment throws **`PaymentBlockedError`** with a `reason`: `budget`, `max_payment`, `max_payments`, `unknown_value`, `pay_safe`, `pay_safe_unavailable` or `stopped`. The error also carries the `payment`, and Pay Safe's `verdict` when that was the cause.
+
+Failed calls aren't counted: a payment only counts when the service accepted it (a `PAYMENT-RESPONSE` header or a 2xx answer). x402 v1 and v2 are both supported.
+
+## Pay Safe (optional, off by default)
+
+With `paySafe: true`, each payment is checked by [Pay Safe](https://agent-deals.gm-tools.workers.dev/trust) before it's sent. It returns **GO / CAUTION / STOP**:
+
+- **Is the service working?** It's monitored continuously across ~25,000 paid agent APIs.
+- **Is the price fair?** It compares the price with the service's own listing, what it charged before, and similar services.
+- **Is the wallet safe?** It checks scam lists and burn addresses, and whether this is the same wallet the service normally uses. A different wallet can mean a tampered payment request.
+
+**What is sent:** the service URL and the payment terms (amount, asset, network, pay-to wallet). **Never** the signature, your keys or your request content. Answers are cached for a minute. The check is free. Pay Safe is run by the author of this package, and its accuracy tests are [published](https://agent-deals.gm-tools.workers.dev/trust).
+
+## Also for Python
+
+[`agentseatbelt`](https://pypi.org/project/agentseatbelt/) does the same for Python agents (httpx, requests and Coinbase's `x402` client), plus LLM cost budgets, rate limits and loop detection.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,323 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PAY_SAFE_URL: () => PAY_SAFE_URL,
+  PaymentBlockedError: () => PaymentBlockedError,
+  Seatbelt: () => Seatbelt,
+  createSeatbelt: () => createSeatbelt,
+  hasPayment: () => hasPayment,
+  parsePayment: () => parsePayment,
+  parseQuote: () => parseQuote
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/payment.ts
+var PAYMENT_HEADERS = ["payment-signature", "x-payment"];
+var RESPONSE_HEADERS = ["payment-response", "x-payment-response"];
+var USDC = /* @__PURE__ */ new Set([
+  "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+  // Base
+  "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+  // Base Sepolia
+  "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+  // Ethereum
+  "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
+  // Polygon
+  "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
+  // Arbitrum
+  "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+  // Optimism
+  "epjfwdd5aufqssqem2qn1xzybapc8g4wegkzwytdt1v"
+  // Solana (lowercased)
+]);
+function decodeBase64Json(value) {
+  const text = value.trim();
+  try {
+    const binary = atob(text);
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+  } catch {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  }
+}
+function toBigInt(value) {
+  try {
+    return value === void 0 || value === null || value === "" ? null : BigInt(String(value));
+  } catch {
+    return null;
+  }
+}
+var usdOf = (asset, raw) => raw !== null && asset && USDC.has(asset.toLowerCase()) ? Number(raw) / 1e6 : null;
+var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+function hasPayment(headers) {
+  return PAYMENT_HEADERS.some((h) => headers.get(h));
+}
+function isSettled(headers) {
+  return RESPONSE_HEADERS.some((h) => headers.get(h));
+}
+function parseQuote(headers, body) {
+  const raw = headers.get("payment-required");
+  const quote = obj(raw ? decodeBase64Json(raw) : body);
+  const accepts = quote?.accepts;
+  return Array.isArray(accepts) ? accepts.filter((a) => obj(a)) : [];
+}
+function parsePayment(headers, quotes = []) {
+  const raw = PAYMENT_HEADERS.map((h) => headers.get(h)).find(Boolean);
+  if (!raw) return null;
+  const data = obj(decodeBase64Json(raw));
+  if (!data) return { version: 0, network: "", payTo: null, asset: null, rawAmount: null, usd: null, terms: null };
+  const auth = obj(obj(data.payload)?.authorization) ?? {};
+  const accepted = obj(data.accepted);
+  if (accepted) {
+    const rawAmount2 = toBigInt(accepted.amount);
+    const asset2 = typeof accepted.asset === "string" ? accepted.asset : null;
+    return {
+      version: 2,
+      network: String(accepted.network ?? ""),
+      payTo: accepted.payTo ?? auth.to ?? null,
+      asset: asset2,
+      rawAmount: rawAmount2,
+      usd: usdOf(asset2, rawAmount2),
+      terms: accepted
+    };
+  }
+  const payTo = typeof auth.to === "string" ? auth.to : null;
+  const rawAmount = toBigInt(auth.value);
+  const network = String(data.network ?? "");
+  const match = quotes.find((q) => String(q.payTo ?? "").toLowerCase() === String(payTo ?? "").toLowerCase() && String(q.network ?? "") === network);
+  const asset = match && typeof match.asset === "string" ? match.asset : null;
+  const terms = match ? { ...match, network, asset: asset ?? "", payTo: payTo ?? "", amount: rawAmount !== null ? rawAmount.toString() : String(match.maxAmountRequired ?? "0") } : null;
+  return { version: 1, network, payTo, asset, rawAmount, usd: usdOf(asset, rawAmount), terms };
+}
+function describe(p) {
+  const amount = p.usd !== null ? `$${Number(p.usd.toPrecision(6))}` : `${p.rawAmount ?? "?"} units of ${p.asset ?? "an unknown asset"}`;
+  return `${amount} to ${p.payTo ?? "?"} on ${p.network || "?"}`;
+}
+
+// src/seatbelt.ts
+var PAY_SAFE_URL = "https://agent-deals.gm-tools.workers.dev/v1/preflight";
+var PAY_SAFE_CACHE_MS = 6e4;
+var MAX_EVENTS = 200;
+var PaymentBlockedError = class extends Error {
+  reason;
+  payment;
+  verdict;
+  constructor(reason, message, payment, verdict) {
+    super(message);
+    this.name = "PaymentBlockedError";
+    this.reason = reason;
+    this.payment = payment;
+    this.verdict = verdict;
+  }
+};
+function requestParts(input, init) {
+  const isRequest = typeof Request !== "undefined" && input instanceof Request;
+  const url = isRequest ? input.url : input instanceof URL ? input.href : String(input);
+  const method = (init?.method ?? (isRequest ? input.method : "GET")).toUpperCase();
+  const headers = new Headers(init?.headers ?? (isRequest ? input.headers : void 0));
+  return { url, method, headers };
+}
+var Seatbelt = class {
+  options;
+  spent = 0;
+  pending = 0;
+  stats = { payments: 0, blocked: 0, unvaluedPayments: 0, paySafeChecks: 0 };
+  stopped = false;
+  events = [];
+  quotes = /* @__PURE__ */ new Map();
+  paySafeAnswers = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    if (options.paySafeBlock && !["stop", "caution"].includes(options.paySafeBlock)) {
+      throw new Error('paySafeBlock must be "stop" or "caution"');
+    }
+    this.options = options;
+  }
+  /**
+   * A fetch that checks every x402 payment before sending it. Pass it to your x402 client:
+   *
+   *     const fetchWithPayment = wrapFetchWithPayment(seatbelt.wrap(fetch), client);
+   */
+  wrap(baseFetch = globalThis.fetch) {
+    const wrapped = async (input, init) => {
+      const { url, method, headers } = requestParts(input, init);
+      const payment = hasPayment(headers) ? await this.checkPayment(url, method, headers, baseFetch) : null;
+      let response;
+      try {
+        response = await baseFetch(input, init);
+      } catch (error) {
+        if (payment) this.release(payment, url, "the request failed");
+        throw error;
+      }
+      await this.recordResponse(url, response, payment);
+      return response;
+    };
+    return wrapped;
+  }
+  /** Stop every further payment (an emergency stop). */
+  stop() {
+    this.stopped = true;
+  }
+  report() {
+    return {
+      ...this.stats,
+      spentUsd: Math.round(this.spent * 1e6) / 1e6,
+      pendingUsd: Math.round(this.pending * 1e6) / 1e6,
+      stopped: this.stopped,
+      events: [...this.events]
+    };
+  }
+  // ---- internals -------------------------------------------------------------------------------------------
+  event(type, detail, url, payment) {
+    const ev = { time: Date.now(), type, detail, url, payment };
+    this.events.push(ev);
+    if (this.events.length > MAX_EVENTS) this.events.shift();
+    try {
+      this.options.onEvent?.(ev);
+    } catch {
+    }
+  }
+  block(reason, why, payment, url, verdict) {
+    this.stats.blocked++;
+    const message = `x402-seatbelt blocked a payment of ${describe(payment)}: ${why}`;
+    this.event("blocked", message, url, payment);
+    throw new PaymentBlockedError(reason, message, payment, verdict);
+  }
+  /** Limits, then (optionally) Pay Safe. Reserves the amount so parallel payments can't overshoot the budget. */
+  async checkPayment(url, method, headers, baseFetch) {
+    const o = this.options;
+    const payment = parsePayment(headers, this.quotes.get(url));
+    if (!payment) return null;
+    this.checkLimits(payment, url);
+    if (payment.usd !== null) this.pending += payment.usd;
+    try {
+      if (o.paySafe) await this.paySafe(url, method, payment, baseFetch);
+      this.checkLimits(payment, url, payment.usd ?? 0);
+    } catch (error) {
+      if (payment.usd !== null) this.pending -= payment.usd;
+      throw error;
+    }
+    return payment;
+  }
+  checkLimits(payment, url, reservedByThis = 0) {
+    const o = this.options;
+    if (this.stopped) this.block("stopped", "the seatbelt was stopped", payment, url);
+    if (o.maxPayments !== void 0 && this.stats.payments >= o.maxPayments) {
+      this.block("max_payments", `maximum of ${o.maxPayments} payments reached`, payment, url);
+    }
+    if (o.maxPaymentUsd !== void 0) {
+      if (payment.usd === null) this.block("unknown_value", "its dollar value is unknown (not USDC), so maxPaymentUsd can't be applied", payment, url);
+      if (payment.usd > o.maxPaymentUsd) this.block("max_payment", `above maxPaymentUsd ($${o.maxPaymentUsd})`, payment, url);
+    }
+    if (o.maxTotalUsd !== void 0 && payment.usd !== null) {
+      const committed = this.spent + this.pending - reservedByThis;
+      if (committed + payment.usd > o.maxTotalUsd + 1e-12) {
+        this.block("budget", `it would exceed maxTotalUsd ($${o.maxTotalUsd}; $${committed.toFixed(6)} already committed)`, payment, url);
+      }
+    }
+  }
+  async paySafe(url, method, payment, baseFetch) {
+    const o = this.options;
+    const key = [url, payment.payTo?.toLowerCase(), payment.rawAmount?.toString(), payment.asset?.toLowerCase()].join("|");
+    const cached = this.paySafeAnswers.get(key);
+    let answer;
+    if (cached && Date.now() - cached.at < PAY_SAFE_CACHE_MS) {
+      answer = cached.answer;
+    } else {
+      const terms = payment.terms ?? {
+        scheme: "exact",
+        network: payment.network,
+        amount: (payment.rawAmount ?? 0n).toString(),
+        asset: payment.asset ?? "",
+        payTo: payment.payTo ?? ""
+      };
+      try {
+        const res = await baseFetch(o.paySafeUrl ?? PAY_SAFE_URL, {
+          method: "POST",
+          headers: { "content-type": "application/json", "user-agent": "x402-seatbelt" },
+          body: JSON.stringify({ url, method, payment_required: { x402Version: 2, resource: { url }, accepts: [terms] } }),
+          signal: AbortSignal.timeout(o.paySafeTimeoutMs ?? 8e3)
+        });
+        const body = await res.json();
+        if (!res.ok || !["go", "caution", "stop"].includes(body?.verdict)) throw new Error(`unexpected answer (HTTP ${res.status})`);
+        answer = body;
+        this.paySafeAnswers.set(key, { at: Date.now(), answer });
+      } catch (error) {
+        this.event("pay_safe", `check unavailable (${error.message}) for ${describe(payment)}`, url, payment);
+        if (o.paySafeFailClosed) this.block("pay_safe_unavailable", "Pay Safe couldn't be reached (paySafeFailClosed)", payment, url);
+        return;
+      }
+    }
+    this.stats.paySafeChecks++;
+    this.event("pay_safe", `${answer.verdict.toUpperCase()} for ${describe(payment)}: ${answer.summary ?? ""}`, url, payment);
+    if (answer.verdict === "stop" || answer.verdict === "caution" && o.paySafeBlock === "caution") {
+      this.block("pay_safe", `Pay Safe says ${answer.verdict.toUpperCase()}: ${answer.summary ?? ""}`, payment, url, answer);
+    }
+  }
+  release(payment, url, why) {
+    if (payment.usd !== null) this.pending -= payment.usd;
+    this.event("not_charged", `not charged (${why}): ${describe(payment)}`, url, payment);
+  }
+  async recordResponse(url, response, payment) {
+    if (response.status === 402) {
+      let body;
+      if (!response.headers.get("payment-required")) {
+        try {
+          body = await response.clone().json();
+        } catch {
+          body = void 0;
+        }
+      }
+      const quotes = parseQuote(response.headers, body);
+      if (quotes.length) this.quotes.set(url, quotes);
+    }
+    if (!payment) return;
+    if (!(isSettled(response.headers) || response.ok)) {
+      this.release(payment, url, `HTTP ${response.status}`);
+      return;
+    }
+    this.stats.payments++;
+    if (payment.usd === null) {
+      this.stats.unvaluedPayments++;
+      this.event("payment", `paid ${describe(payment)} (not valued in USD)`, url, payment);
+      return;
+    }
+    this.pending -= payment.usd;
+    this.spent += payment.usd;
+    this.event("payment", `paid ${describe(payment)} (total $${this.spent.toFixed(6)})`, url, payment);
+  }
+};
+function createSeatbelt(options = {}) {
+  return new Seatbelt(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PAY_SAFE_URL,
+  PaymentBlockedError,
+  Seatbelt,
+  createSeatbelt,
+  hasPayment,
+  parsePayment,
+  parseQuote
+});

package/dist/index.d.cts

@@ -0,0 +1,127 @@
+/** Payment terms, in x402 v2 shape. */
+interface PaymentTerms {
+    scheme?: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    [key: string]: unknown;
+}
+interface Payment {
+    version: number;
+    network: string;
+    payTo: string | null;
+    asset: string | null;
+    /** Amount in the asset's smallest unit. */
+    rawAmount: bigint | null;
+    /** Dollar value for USDC payments; null when the asset or amount is unknown. */
+    usd: number | null;
+    /** The terms the client accepted (v2), or rebuilt from the 402 quote (v1). */
+    terms: PaymentTerms | null;
+}
+type HeaderSource = {
+    get(name: string): string | null;
+};
+declare function hasPayment(headers: HeaderSource): boolean;
+/** The payment options in a 402 answer: the PAYMENT-REQUIRED header, or (x402 v1) the JSON body. */
+declare function parseQuote(headers: HeaderSource, body?: unknown): Record<string, unknown>[];
+/** The payment carried by a request's headers, or null. `quotes` are the options from the 402 answer it
+ * responds to (x402 v1 payments don't name their asset). */
+declare function parsePayment(headers: HeaderSource, quotes?: Record<string, unknown>[]): Payment | null;
+
+declare const PAY_SAFE_URL = "https://agent-deals.gm-tools.workers.dev/v1/preflight";
+interface SeatbeltOptions {
+    /** Total budget for all payments made through this seatbelt (USDC). A payment that would cross it is never sent. */
+    maxTotalUsd?: number;
+    /** Block any single payment above this (USDC). Payments in other assets are blocked too, since their value is unknown. */
+    maxPaymentUsd?: number;
+    /** Block payments after this many. */
+    maxPayments?: number;
+    /**
+     * Before each payment is sent, ask the Pay Safe service whether it looks safe: is the service working, is the
+     * price fair, is the wallet safe and the one the service normally uses. Sends the service URL and the payment
+     * terms (amount, asset, network, pay-to wallet), never the signature or any key. Off by default.
+     */
+    paySafe?: boolean;
+    /** "stop" (default) blocks payments Pay Safe rates STOP; "caution" also blocks CAUTION. */
+    paySafeBlock?: "stop" | "caution";
+    /** Block payments when Pay Safe can't be reached (default: let them through). */
+    paySafeFailClosed?: boolean;
+    paySafeUrl?: string;
+    paySafeTimeoutMs?: number;
+    /** Called for every event (payments, blocks, Pay Safe answers). */
+    onEvent?: (event: SeatbeltEvent) => void;
+}
+type BlockReason = "max_payment" | "budget" | "max_payments" | "unknown_value" | "pay_safe" | "pay_safe_unavailable" | "stopped";
+interface PaySafeVerdict {
+    verdict: "go" | "caution" | "stop";
+    summary?: string;
+    findings?: {
+        level: string;
+        code: string;
+        message: string;
+    }[];
+    [key: string]: unknown;
+}
+interface SeatbeltEvent {
+    time: number;
+    type: "payment" | "not_charged" | "blocked" | "pay_safe" | "quote";
+    detail: string;
+    url?: string;
+    payment?: Payment;
+}
+interface SeatbeltReport {
+    /** Payments that went through. */
+    payments: number;
+    /** Their USDC value. */
+    spentUsd: number;
+    /** Payments sent and still waiting for an answer. */
+    pendingUsd: number;
+    /** Payments stopped before they were sent. */
+    blocked: number;
+    /** Payments in assets other than USDC (not counted in spentUsd). */
+    unvaluedPayments: number;
+    paySafeChecks: number;
+    stopped: boolean;
+    events: SeatbeltEvent[];
+}
+/** A payment was stopped before it was sent: nothing was paid, the signed payment never left this machine. */
+declare class PaymentBlockedError extends Error {
+    readonly reason: BlockReason;
+    readonly payment: Payment;
+    readonly verdict?: PaySafeVerdict;
+    constructor(reason: BlockReason, message: string, payment: Payment, verdict?: PaySafeVerdict);
+}
+type Fetch = typeof fetch;
+declare class Seatbelt {
+    private readonly options;
+    private spent;
+    private pending;
+    private stats;
+    private stopped;
+    private events;
+    private quotes;
+    private paySafeAnswers;
+    constructor(options?: SeatbeltOptions);
+    /**
+     * A fetch that checks every x402 payment before sending it. Pass it to your x402 client:
+     *
+     *     const fetchWithPayment = wrapFetchWithPayment(seatbelt.wrap(fetch), client);
+     */
+    wrap(baseFetch?: Fetch): Fetch;
+    /** Stop every further payment (an emergency stop). */
+    stop(): void;
+    report(): SeatbeltReport;
+    private event;
+    private block;
+    /** Limits, then (optionally) Pay Safe. Reserves the amount so parallel payments can't overshoot the budget. */
+    private checkPayment;
+    private checkLimits;
+    private paySafe;
+    private release;
+    private recordResponse;
+}
+/** Create a seatbelt. `seatbelt.wrap(fetch)` gives a fetch that checks every x402 payment before it's sent. */
+declare function createSeatbelt(options?: SeatbeltOptions): Seatbelt;
+
+export { type BlockReason, PAY_SAFE_URL, type PaySafeVerdict, type Payment, PaymentBlockedError, type PaymentTerms, Seatbelt, type SeatbeltEvent, type SeatbeltOptions, type SeatbeltReport, createSeatbelt, hasPayment, parsePayment, parseQuote };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+/** Payment terms, in x402 v2 shape. */
+interface PaymentTerms {
+    scheme?: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    [key: string]: unknown;
+}
+interface Payment {
+    version: number;
+    network: string;
+    payTo: string | null;
+    asset: string | null;
+    /** Amount in the asset's smallest unit. */
+    rawAmount: bigint | null;
+    /** Dollar value for USDC payments; null when the asset or amount is unknown. */
+    usd: number | null;
+    /** The terms the client accepted (v2), or rebuilt from the 402 quote (v1). */
+    terms: PaymentTerms | null;
+}
+type HeaderSource = {
+    get(name: string): string | null;
+};
+declare function hasPayment(headers: HeaderSource): boolean;
+/** The payment options in a 402 answer: the PAYMENT-REQUIRED header, or (x402 v1) the JSON body. */
+declare function parseQuote(headers: HeaderSource, body?: unknown): Record<string, unknown>[];
+/** The payment carried by a request's headers, or null. `quotes` are the options from the 402 answer it
+ * responds to (x402 v1 payments don't name their asset). */
+declare function parsePayment(headers: HeaderSource, quotes?: Record<string, unknown>[]): Payment | null;
+
+declare const PAY_SAFE_URL = "https://agent-deals.gm-tools.workers.dev/v1/preflight";
+interface SeatbeltOptions {
+    /** Total budget for all payments made through this seatbelt (USDC). A payment that would cross it is never sent. */
+    maxTotalUsd?: number;
+    /** Block any single payment above this (USDC). Payments in other assets are blocked too, since their value is unknown. */
+    maxPaymentUsd?: number;
+    /** Block payments after this many. */
+    maxPayments?: number;
+    /**
+     * Before each payment is sent, ask the Pay Safe service whether it looks safe: is the service working, is the
+     * price fair, is the wallet safe and the one the service normally uses. Sends the service URL and the payment
+     * terms (amount, asset, network, pay-to wallet), never the signature or any key. Off by default.
+     */
+    paySafe?: boolean;
+    /** "stop" (default) blocks payments Pay Safe rates STOP; "caution" also blocks CAUTION. */
+    paySafeBlock?: "stop" | "caution";
+    /** Block payments when Pay Safe can't be reached (default: let them through). */
+    paySafeFailClosed?: boolean;
+    paySafeUrl?: string;
+    paySafeTimeoutMs?: number;
+    /** Called for every event (payments, blocks, Pay Safe answers). */
+    onEvent?: (event: SeatbeltEvent) => void;
+}
+type BlockReason = "max_payment" | "budget" | "max_payments" | "unknown_value" | "pay_safe" | "pay_safe_unavailable" | "stopped";
+interface PaySafeVerdict {
+    verdict: "go" | "caution" | "stop";
+    summary?: string;
+    findings?: {
+        level: string;
+        code: string;
+        message: string;
+    }[];
+    [key: string]: unknown;
+}
+interface SeatbeltEvent {
+    time: number;
+    type: "payment" | "not_charged" | "blocked" | "pay_safe" | "quote";
+    detail: string;
+    url?: string;
+    payment?: Payment;
+}
+interface SeatbeltReport {
+    /** Payments that went through. */
+    payments: number;
+    /** Their USDC value. */
+    spentUsd: number;
+    /** Payments sent and still waiting for an answer. */
+    pendingUsd: number;
+    /** Payments stopped before they were sent. */
+    blocked: number;
+    /** Payments in assets other than USDC (not counted in spentUsd). */
+    unvaluedPayments: number;
+    paySafeChecks: number;
+    stopped: boolean;
+    events: SeatbeltEvent[];
+}
+/** A payment was stopped before it was sent: nothing was paid, the signed payment never left this machine. */
+declare class PaymentBlockedError extends Error {
+    readonly reason: BlockReason;
+    readonly payment: Payment;
+    readonly verdict?: PaySafeVerdict;
+    constructor(reason: BlockReason, message: string, payment: Payment, verdict?: PaySafeVerdict);
+}
+type Fetch = typeof fetch;
+declare class Seatbelt {
+    private readonly options;
+    private spent;
+    private pending;
+    private stats;
+    private stopped;
+    private events;
+    private quotes;
+    private paySafeAnswers;
+    constructor(options?: SeatbeltOptions);
+    /**
+     * A fetch that checks every x402 payment before sending it. Pass it to your x402 client:
+     *
+     *     const fetchWithPayment = wrapFetchWithPayment(seatbelt.wrap(fetch), client);
+     */
+    wrap(baseFetch?: Fetch): Fetch;
+    /** Stop every further payment (an emergency stop). */
+    stop(): void;
+    report(): SeatbeltReport;
+    private event;
+    private block;
+    /** Limits, then (optionally) Pay Safe. Reserves the amount so parallel payments can't overshoot the budget. */
+    private checkPayment;
+    private checkLimits;
+    private paySafe;
+    private release;
+    private recordResponse;
+}
+/** Create a seatbelt. `seatbelt.wrap(fetch)` gives a fetch that checks every x402 payment before it's sent. */
+declare function createSeatbelt(options?: SeatbeltOptions): Seatbelt;
+
+export { type BlockReason, PAY_SAFE_URL, type PaySafeVerdict, type Payment, PaymentBlockedError, type PaymentTerms, Seatbelt, type SeatbeltEvent, type SeatbeltOptions, type SeatbeltReport, createSeatbelt, hasPayment, parsePayment, parseQuote };

package/dist/index.js

@@ -0,0 +1,290 @@
+// src/payment.ts
+var PAYMENT_HEADERS = ["payment-signature", "x-payment"];
+var RESPONSE_HEADERS = ["payment-response", "x-payment-response"];
+var USDC = /* @__PURE__ */ new Set([
+  "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+  // Base
+  "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+  // Base Sepolia
+  "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+  // Ethereum
+  "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
+  // Polygon
+  "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
+  // Arbitrum
+  "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+  // Optimism
+  "epjfwdd5aufqssqem2qn1xzybapc8g4wegkzwytdt1v"
+  // Solana (lowercased)
+]);
+function decodeBase64Json(value) {
+  const text = value.trim();
+  try {
+    const binary = atob(text);
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+  } catch {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  }
+}
+function toBigInt(value) {
+  try {
+    return value === void 0 || value === null || value === "" ? null : BigInt(String(value));
+  } catch {
+    return null;
+  }
+}
+var usdOf = (asset, raw) => raw !== null && asset && USDC.has(asset.toLowerCase()) ? Number(raw) / 1e6 : null;
+var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+function hasPayment(headers) {
+  return PAYMENT_HEADERS.some((h) => headers.get(h));
+}
+function isSettled(headers) {
+  return RESPONSE_HEADERS.some((h) => headers.get(h));
+}
+function parseQuote(headers, body) {
+  const raw = headers.get("payment-required");
+  const quote = obj(raw ? decodeBase64Json(raw) : body);
+  const accepts = quote?.accepts;
+  return Array.isArray(accepts) ? accepts.filter((a) => obj(a)) : [];
+}
+function parsePayment(headers, quotes = []) {
+  const raw = PAYMENT_HEADERS.map((h) => headers.get(h)).find(Boolean);
+  if (!raw) return null;
+  const data = obj(decodeBase64Json(raw));
+  if (!data) return { version: 0, network: "", payTo: null, asset: null, rawAmount: null, usd: null, terms: null };
+  const auth = obj(obj(data.payload)?.authorization) ?? {};
+  const accepted = obj(data.accepted);
+  if (accepted) {
+    const rawAmount2 = toBigInt(accepted.amount);
+    const asset2 = typeof accepted.asset === "string" ? accepted.asset : null;
+    return {
+      version: 2,
+      network: String(accepted.network ?? ""),
+      payTo: accepted.payTo ?? auth.to ?? null,
+      asset: asset2,
+      rawAmount: rawAmount2,
+      usd: usdOf(asset2, rawAmount2),
+      terms: accepted
+    };
+  }
+  const payTo = typeof auth.to === "string" ? auth.to : null;
+  const rawAmount = toBigInt(auth.value);
+  const network = String(data.network ?? "");
+  const match = quotes.find((q) => String(q.payTo ?? "").toLowerCase() === String(payTo ?? "").toLowerCase() && String(q.network ?? "") === network);
+  const asset = match && typeof match.asset === "string" ? match.asset : null;
+  const terms = match ? { ...match, network, asset: asset ?? "", payTo: payTo ?? "", amount: rawAmount !== null ? rawAmount.toString() : String(match.maxAmountRequired ?? "0") } : null;
+  return { version: 1, network, payTo, asset, rawAmount, usd: usdOf(asset, rawAmount), terms };
+}
+function describe(p) {
+  const amount = p.usd !== null ? `$${Number(p.usd.toPrecision(6))}` : `${p.rawAmount ?? "?"} units of ${p.asset ?? "an unknown asset"}`;
+  return `${amount} to ${p.payTo ?? "?"} on ${p.network || "?"}`;
+}
+
+// src/seatbelt.ts
+var PAY_SAFE_URL = "https://agent-deals.gm-tools.workers.dev/v1/preflight";
+var PAY_SAFE_CACHE_MS = 6e4;
+var MAX_EVENTS = 200;
+var PaymentBlockedError = class extends Error {
+  reason;
+  payment;
+  verdict;
+  constructor(reason, message, payment, verdict) {
+    super(message);
+    this.name = "PaymentBlockedError";
+    this.reason = reason;
+    this.payment = payment;
+    this.verdict = verdict;
+  }
+};
+function requestParts(input, init) {
+  const isRequest = typeof Request !== "undefined" && input instanceof Request;
+  const url = isRequest ? input.url : input instanceof URL ? input.href : String(input);
+  const method = (init?.method ?? (isRequest ? input.method : "GET")).toUpperCase();
+  const headers = new Headers(init?.headers ?? (isRequest ? input.headers : void 0));
+  return { url, method, headers };
+}
+var Seatbelt = class {
+  options;
+  spent = 0;
+  pending = 0;
+  stats = { payments: 0, blocked: 0, unvaluedPayments: 0, paySafeChecks: 0 };
+  stopped = false;
+  events = [];
+  quotes = /* @__PURE__ */ new Map();
+  paySafeAnswers = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    if (options.paySafeBlock && !["stop", "caution"].includes(options.paySafeBlock)) {
+      throw new Error('paySafeBlock must be "stop" or "caution"');
+    }
+    this.options = options;
+  }
+  /**
+   * A fetch that checks every x402 payment before sending it. Pass it to your x402 client:
+   *
+   *     const fetchWithPayment = wrapFetchWithPayment(seatbelt.wrap(fetch), client);
+   */
+  wrap(baseFetch = globalThis.fetch) {
+    const wrapped = async (input, init) => {
+      const { url, method, headers } = requestParts(input, init);
+      const payment = hasPayment(headers) ? await this.checkPayment(url, method, headers, baseFetch) : null;
+      let response;
+      try {
+        response = await baseFetch(input, init);
+      } catch (error) {
+        if (payment) this.release(payment, url, "the request failed");
+        throw error;
+      }
+      await this.recordResponse(url, response, payment);
+      return response;
+    };
+    return wrapped;
+  }
+  /** Stop every further payment (an emergency stop). */
+  stop() {
+    this.stopped = true;
+  }
+  report() {
+    return {
+      ...this.stats,
+      spentUsd: Math.round(this.spent * 1e6) / 1e6,
+      pendingUsd: Math.round(this.pending * 1e6) / 1e6,
+      stopped: this.stopped,
+      events: [...this.events]
+    };
+  }
+  // ---- internals -------------------------------------------------------------------------------------------
+  event(type, detail, url, payment) {
+    const ev = { time: Date.now(), type, detail, url, payment };
+    this.events.push(ev);
+    if (this.events.length > MAX_EVENTS) this.events.shift();
+    try {
+      this.options.onEvent?.(ev);
+    } catch {
+    }
+  }
+  block(reason, why, payment, url, verdict) {
+    this.stats.blocked++;
+    const message = `x402-seatbelt blocked a payment of ${describe(payment)}: ${why}`;
+    this.event("blocked", message, url, payment);
+    throw new PaymentBlockedError(reason, message, payment, verdict);
+  }
+  /** Limits, then (optionally) Pay Safe. Reserves the amount so parallel payments can't overshoot the budget. */
+  async checkPayment(url, method, headers, baseFetch) {
+    const o = this.options;
+    const payment = parsePayment(headers, this.quotes.get(url));
+    if (!payment) return null;
+    this.checkLimits(payment, url);
+    if (payment.usd !== null) this.pending += payment.usd;
+    try {
+      if (o.paySafe) await this.paySafe(url, method, payment, baseFetch);
+      this.checkLimits(payment, url, payment.usd ?? 0);
+    } catch (error) {
+      if (payment.usd !== null) this.pending -= payment.usd;
+      throw error;
+    }
+    return payment;
+  }
+  checkLimits(payment, url, reservedByThis = 0) {
+    const o = this.options;
+    if (this.stopped) this.block("stopped", "the seatbelt was stopped", payment, url);
+    if (o.maxPayments !== void 0 && this.stats.payments >= o.maxPayments) {
+      this.block("max_payments", `maximum of ${o.maxPayments} payments reached`, payment, url);
+    }
+    if (o.maxPaymentUsd !== void 0) {
+      if (payment.usd === null) this.block("unknown_value", "its dollar value is unknown (not USDC), so maxPaymentUsd can't be applied", payment, url);
+      if (payment.usd > o.maxPaymentUsd) this.block("max_payment", `above maxPaymentUsd ($${o.maxPaymentUsd})`, payment, url);
+    }
+    if (o.maxTotalUsd !== void 0 && payment.usd !== null) {
+      const committed = this.spent + this.pending - reservedByThis;
+      if (committed + payment.usd > o.maxTotalUsd + 1e-12) {
+        this.block("budget", `it would exceed maxTotalUsd ($${o.maxTotalUsd}; $${committed.toFixed(6)} already committed)`, payment, url);
+      }
+    }
+  }
+  async paySafe(url, method, payment, baseFetch) {
+    const o = this.options;
+    const key = [url, payment.payTo?.toLowerCase(), payment.rawAmount?.toString(), payment.asset?.toLowerCase()].join("|");
+    const cached = this.paySafeAnswers.get(key);
+    let answer;
+    if (cached && Date.now() - cached.at < PAY_SAFE_CACHE_MS) {
+      answer = cached.answer;
+    } else {
+      const terms = payment.terms ?? {
+        scheme: "exact",
+        network: payment.network,
+        amount: (payment.rawAmount ?? 0n).toString(),
+        asset: payment.asset ?? "",
+        payTo: payment.payTo ?? ""
+      };
+      try {
+        const res = await baseFetch(o.paySafeUrl ?? PAY_SAFE_URL, {
+          method: "POST",
+          headers: { "content-type": "application/json", "user-agent": "x402-seatbelt" },
+          body: JSON.stringify({ url, method, payment_required: { x402Version: 2, resource: { url }, accepts: [terms] } }),
+          signal: AbortSignal.timeout(o.paySafeTimeoutMs ?? 8e3)
+        });
+        const body = await res.json();
+        if (!res.ok || !["go", "caution", "stop"].includes(body?.verdict)) throw new Error(`unexpected answer (HTTP ${res.status})`);
+        answer = body;
+        this.paySafeAnswers.set(key, { at: Date.now(), answer });
+      } catch (error) {
+        this.event("pay_safe", `check unavailable (${error.message}) for ${describe(payment)}`, url, payment);
+        if (o.paySafeFailClosed) this.block("pay_safe_unavailable", "Pay Safe couldn't be reached (paySafeFailClosed)", payment, url);
+        return;
+      }
+    }
+    this.stats.paySafeChecks++;
+    this.event("pay_safe", `${answer.verdict.toUpperCase()} for ${describe(payment)}: ${answer.summary ?? ""}`, url, payment);
+    if (answer.verdict === "stop" || answer.verdict === "caution" && o.paySafeBlock === "caution") {
+      this.block("pay_safe", `Pay Safe says ${answer.verdict.toUpperCase()}: ${answer.summary ?? ""}`, payment, url, answer);
+    }
+  }
+  release(payment, url, why) {
+    if (payment.usd !== null) this.pending -= payment.usd;
+    this.event("not_charged", `not charged (${why}): ${describe(payment)}`, url, payment);
+  }
+  async recordResponse(url, response, payment) {
+    if (response.status === 402) {
+      let body;
+      if (!response.headers.get("payment-required")) {
+        try {
+          body = await response.clone().json();
+        } catch {
+          body = void 0;
+        }
+      }
+      const quotes = parseQuote(response.headers, body);
+      if (quotes.length) this.quotes.set(url, quotes);
+    }
+    if (!payment) return;
+    if (!(isSettled(response.headers) || response.ok)) {
+      this.release(payment, url, `HTTP ${response.status}`);
+      return;
+    }
+    this.stats.payments++;
+    if (payment.usd === null) {
+      this.stats.unvaluedPayments++;
+      this.event("payment", `paid ${describe(payment)} (not valued in USD)`, url, payment);
+      return;
+    }
+    this.pending -= payment.usd;
+    this.spent += payment.usd;
+    this.event("payment", `paid ${describe(payment)} (total $${this.spent.toFixed(6)})`, url, payment);
+  }
+};
+function createSeatbelt(options = {}) {
+  return new Seatbelt(options);
+}
+export {
+  PAY_SAFE_URL,
+  PaymentBlockedError,
+  Seatbelt,
+  createSeatbelt,
+  hasPayment,
+  parsePayment,
+  parseQuote
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "x402-seatbelt",
+  "version": "0.1.0",
+  "description": "A seatbelt for AI agents that pay with x402: spending budgets, per-payment caps and an optional Pay Safe check before every payment. Wraps fetch; works with @x402/fetch.",
+  "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"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/seatbelt.test.ts"
+  },
+  "keywords": [
+    "x402",
+    "agents",
+    "ai-agents",
+    "payments",
+    "usdc",
+    "budget",
+    "safety",
+    "fetch",
+    "seatbelt",
+    "spending-limit"
+  ],
+  "author": "gmahar82-stack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gmahar82-stack/x402-seatbelt.git"
+  },
+  "homepage": "https://github.com/gmahar82-stack/x402-seatbelt#readme",
+  "bugs": {
+    "url": "https://github.com/gmahar82-stack/x402-seatbelt/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@x402/core": "^2.27.0",
+    "@x402/evm": "^2.27.0",
+    "@x402/fetch": "^2.27.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "viem": "^2.56.9"
+  }
+}