agent402-mcp 0.13.15 → 0.13.17

package/README.md

@@ -15,7 +15,7 @@ wrapped with `mppx`'s `McpClient.wrap()` (USDC on Base/Celo, or native Tempo)
 pays and retries on its own, receipt in `_meta`. For no rate limit, or to pay
 over x402 or with a credits key already issued, run this package locally:
 
-With a funded wallet (USDC on any EVM rail the server offers - Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism - or USDG on Robinhood Chain, or USDC on Solana via `SOLANA_AGENT_KEY`; the service also settles on Stellar and Algorand, which this package does not sign) - every tool available:
+With a funded wallet (USDC on any EVM rail the server offers - Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc - or USDG on Robinhood Chain, or USDC on Solana via `SOLANA_AGENT_KEY`; the service also settles on Stellar and Algorand, which this package does not sign) - every tool available:
 
 ```json
 {
@@ -64,21 +64,33 @@ Every variable the server reads (all optional):
 | `AGENT_KEY` | _(unset)_ | Hex private key of an EVM wallet funded with USDC on Base (or another EVM chain the server offers), or USDG on Robinhood Chain. |
 | `SOLANA_AGENT_KEY` | _(unset)_ | Base58 secret key (or JSON byte array) of a Solana wallet funded with USDC on Solana. |
 | `AGENT402_CREDITS_KEY` | _(unset)_ | A prepaid credits key (`a402_...`) already issued (new credits are not on sale). Sent as `Authorization: Bearer` on every catalog call; the server debits the list price only on a successful (200) call and answers `X-Credits-Balance`. Used only when no wallet key is set (a wallet key wins); in credits mode every call - pure-CPU tools included - is debited from the key. |
-| `AGENT402_URL` | `https://agent402.tools` | Target service (point at your own deployment). |
+| `AGENT402_URL` | `https://agent402.tools` | Target service (point at your own deployment). Paid calls never follow redirects, so use the address that serves the routes directly; a redirect is refused with the origin to use. |
 | `AGENT402_TOOLS` | curated set | Comma-separated slugs to expose as first-class tools. |
-| `AGENT402_MAX_PER_CALL` | unlimited | Refuse any single call priced above this many USD (e.g. `0.01`). Applies to the wallet and the credits path. |
-| `AGENT402_BUDGET` | unlimited | Hard cap on total USD spent per session (e.g. `1.00`). Applies to the wallet and the credits path. |
+| `AGENT402_MAX_PER_CALL` | `4` | Refuse any single call priced above this many USD (e.g. `0.05`); `off` disables it. Applies to the wallet and the credits path. |
+| `AGENT402_BUDGET` | no session cap | Opt-in hard cap on total USD spent per session (e.g. `1.00`); unset or `off` means no session cap. Applies to the wallet and the credits path. |
 | `AGENT402_NETWORKS` | _(unset)_ | Restrict + order the chains to pay on - e.g. `robinhood` (USDG on Robinhood Chain), `base,solana`, or a raw CAIP-2 like `eip155:4663`. Unset = the client picks (effectively Base on multi-chain sellers). |
-
-Spend controls are enforced **before a payment is signed** (or a credits call is
-sent) - a runaway model is refused, not billed. `payment.info` reports the
-caps, what's been spent, and what remains. With no wallet key and no credits key,
+| `AGENT402_ASYNC` | `auto` | Slow routes (reports, video, the premium image; `async.recommended` on their `/api/pricing` row) are paid with `Prefer: respond-async` and collected from their job link, so a long run never outlives the connection. `off` waits on the connection instead; `always` uses a job on every route that runs as one. |
+| `AGENT402_ASYNC_TIMEOUT_MS` | `900000` | How long to poll a job before answering with its link (`structuredContent.jobUrl`) to collect later. |
+
+The per-call cap is on by default and the session budget is opt-in; both are
+enforced on the payment that is signed (or before a credits call is sent) - a
+runaway model is refused, not billed. The
+wallet's x402 client carries a policy that drops every payment option over the
+per-call cap or what is left of the budget, so the 402 the wallet signs is held
+to the caps, and a wallet call sends no unpaid preflight first. Each option is priced from the
+known decimals of its asset (USDC on each rail, USDG on Robinhood Chain), never
+from a decimals value in the challenge, and an option in any other asset is not
+signed. A value that is not a USD amount or `off` reads as the default (the
+$4 per-call cap; no session cap). Set `AGENT402_BUDGET` to bound what one
+session may spend in total.
+`payment.info` reports the caps, what's been spent, and what remains. With no wallet key and no credits key,
 the server runs in proof-of-work mode (pure-CPU tools stay free). Use dedicated
 low-value wallets for `AGENT_KEY` / `SOLANA_AGENT_KEY`, funded only with what
 you intend to spend. Most tools cost $0.001–$0.02. The routing tiers top out
 at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.101; and the
 report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the ticker pack at $2.00),
-so set `AGENT402_MAX_PER_CALL` if you want a hard per-call ceiling.
+so the default per-call cap of $4 covers every tool; set `AGENT402_MAX_PER_CALL` lower for a
+tighter ceiling.
 
 ## How it works
 
@@ -86,8 +98,9 @@ so set `AGENT402_MAX_PER_CALL` if you want a hard per-call ceiling.
 - **Flagship tools** are exposed as first-class MCP tools under dotted names - `web.search`, `web.answer`, `web.news`, `browser.render`, `market.quote`, `audio.transcribe`, `memory.read`, `memory.write` - search/answer is the front door. Override the set with `AGENT402_TOOLS` (slugs; a non-flagship slug is listed as its snake_case name).
 - **Decide** (`decide.plan`, `decide.execute`, `decide.feedback`): describe a job and get a call-ready plan over the catalog and outside x402 sellers (tools in order, fallbacks, validated params, chained steps), then run it yourself or through Agent402. Listed when the server offers Decide; see https://agent402.tools/decide.
 - The rest of the 500+ tool catalog is reachable via the meta tools `catalog.search` / `catalog.find` + `catalog.call` - keeping your context window small. The same dotted names are listed on the hosted connector; the older snake names (`search_tools`, `find_tool`, `call_tool`, `get_payment_info`, `describe_server`, `list_top_sellers`, and the flagship `search_web` …) remain accepted as CallTool aliases, so existing configs keep working.
-- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains, Robinhood Chain included; `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; with only a credits key it sends `Authorization: Bearer a402_…` and the server debits the balance on success; with neither it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Stellar and Algorand, plus USDG on Robinhood Chain - 12 chains total - for callers using a raw x402 client rather than this package.)
+- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains, Robinhood Chain included; `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; with only a credits key it sends `Authorization: Bearer a402_…` and the server debits the balance on success; with neither it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc, Stellar and Algorand, plus USDG on Robinhood Chain - 13 chains total - for callers using a raw x402 client rather than this package.)
 - Since 0.13.15 the server's requests to the catalog and to sellers (catalog reads, the 402 and the paid retry) refuse a TLS chain through one of the intermediate CAs listed in `networks.js` (keys reported recoverable in Mozilla bug 2083449), keyed on each certificate's SubjectPublicKeyInfo hash, on a dedicated dispatcher. With a proxy or custom dispatcher installed, requests go out through it unchanged.
+- **Slow routes run as jobs** (since 0.13.17): a paid call to a route the catalog marks slow carries `Prefer: respond-async`, answers `202` with a job link, and the server polls `GET /api/jobs/{id}` (free), waiting `Retry-After` seconds between polls, until the answer is ready, reading the job's `state` and falling back to its `status`. Payment settles only on the delivered answer. A caller that sends a `progressToken` gets `notifications/progress` from the job's stage, steps and ETA. A job still running when `AGENT402_ASYNC_TIMEOUT_MS` ends comes back with its `jobUrl` instead.
 - `payment.info` tells the model which mode it's in and what a wallet or a credits key would unlock.
 - `server.describe` returns orientation (flagship-first tools, install one-liners, free vs paid, discovery URLs). Call it first.
 - `sellers.list` returns the live leaderboards - `wire: "x402"` (default) ranks x402 sellers settling the most USDC (primarily on Base) in the last ~24h from on-chain transfers; `wire: "mpp"` ranks live-verified MPP sellers by inbound USDC.e transfers on Tempo. Free to call (no payment, no proof-of-work). Useful for agents discovering the wider x402 / MPP economy beyond this single service's catalog.

package/async-job.js

@@ -0,0 +1,125 @@
+// Collect a paid call that the server answered as a job.
+//
+// A slow Agent402 route (its /api/pricing row carries async.recommended) takes
+// longer than many clients wait. Sent with "Prefer: respond-async", the paid
+// call answers 202 with a job link at once; the server runs it with this
+// call's payment and settles only when the answer is ready. This module polls
+// the job link (free), waiting Retry-After seconds between polls, and turns the
+// final job into an ordinary Response: the route's own status, headers (the
+// payment receipt) and body. A job that is still running when the caller's
+// overall timeout ends throws AsyncJobPendingError carrying the job link, so
+// the answer can still be collected later (the payment, if any, settles only
+// on a delivered result, which may still happen).
+//
+// The job link must be on the same origin as the server: a Location naming
+// another host is refused rather than fetched.
+//
+// Kept in lockstep with client/async-job.js (agent402-client).
+
+export const DEFAULT_ASYNC_TIMEOUT_MS = 15 * 60_000;
+const MIN_WAIT_MS = 1_000;
+const MAX_WAIT_MS = 30_000;
+const MAX_POLL_FAILURES = 5;
+
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** True when this call should ask for a job: mode "auto" (default) for routes
+ *  the catalog marks recommended, true for any route that runs as a job,
+ *  false never. `advice` is the catalog row's `async` block. */
+export function shouldRequestAsync(advice, mode = "auto") {
+  if (!advice || typeof advice !== "object" || mode === false || mode === "off") return false;
+  if (mode === true || mode === "always") return true;
+  return advice.recommended === true;
+}
+
+export class AsyncJobPendingError extends Error {
+  constructor(message, { jobUrl, slug, job } = {}) {
+    super(message);
+    this.name = "AsyncJobPendingError";
+    Object.assign(this, { jobUrl, slug, job: job || null, mayBeCharged: true });
+  }
+}
+
+/** Milliseconds to wait before the next poll, from Retry-After or the body. */
+export function retryAfterMs(headers, doc) {
+  const h = headers && typeof headers.get === "function" ? headers.get("retry-after") : null;
+  let s = h != null && String(h).trim() !== "" ? Number(h) : NaN;
+  if (!Number.isFinite(s)) s = Number(doc?.pollIntervalSeconds);
+  if (!Number.isFinite(s) || s < 0) s = 5;
+  return Math.max(MIN_WAIT_MS, Math.min(MAX_WAIT_MS, s * 1000));
+}
+
+function sameOrigin(url, baseUrl) {
+  try { return new URL(url).origin === new URL(baseUrl).origin; } catch { return false; }
+}
+
+// The job's lifecycle: `state` (queued | running | succeeded | failed) when
+// the server sends it, else the original `status` (working | completed | failed).
+const STATUS_TO_STATE = { working: "running", completed: "succeeded", failed: "failed", cancelled: "failed" };
+export function jobState(doc) {
+  if (typeof doc?.state === "string" && doc.state) return doc.state;
+  const s = typeof doc?.status === "string" ? doc.status : "";
+  return STATUS_TO_STATE[s] || s || null;
+}
+
+/** An ordinary Response for a finished job's answer. */
+export function responseFromJob(doc) {
+  const done = jobState(doc) === "succeeded";
+  const part = done ? doc.result || {} : doc?.error || {};
+  const status = Number(part.httpStatus) || (done ? 200 : 502);
+  const body = part.body !== undefined ? part.body : done ? {} : { error: part.message || doc?.message || "The job failed." };
+  const headers = { "content-type": "application/json" };
+  for (const [k, v] of Object.entries(part.headers || {})) if (typeof v === "string") headers[k.toLowerCase()] = v;
+  if (!done && doc?.message) headers["x-agent402-job-message"] = String(doc.message).replace(/[^\x20-\x7e]/g, " ").slice(0, 300);
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+/**
+ * Turn a 202 job answer into the route's final Response; any other response
+ * is returned unchanged.
+ * @param {Response} res              the answer to the paid call
+ * @param {object} o
+ * @param {string} o.baseUrl          the server's base URL (the job link must share its origin)
+ * @param {Function} o.fetchImpl      a plain fetch (the job link is free; no payment rides on it)
+ * @param {number} [o.timeoutMs]      overall wait for the job
+ * @param {Function} [o.onProgress]   called with each job document
+ * @param {string} [o.slug]
+ */
+export async function awaitJob(res, { baseUrl, fetchImpl, timeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null, slug = "", sleep = sleepMs, now = () => Date.now() } = {}) {
+  if (!res || res.status !== 202) return res;
+  let doc = {};
+  try { doc = await res.json(); } catch { doc = {}; }
+  const loc = (res.headers && typeof res.headers.get === "function" && res.headers.get("location")) || doc.statusUrl;
+  if (!loc) throw new AsyncJobPendingError(`"${slug}" answered 202 without a job link`, { slug, job: doc });
+  let jobUrl;
+  try { jobUrl = new URL(loc, `${String(baseUrl).replace(/\/$/, "")}/`).href; } catch { jobUrl = null; }
+  if (!jobUrl || !sameOrigin(jobUrl, baseUrl)) throw new AsyncJobPendingError(`"${slug}" named a job link on another origin; it was not followed`, { slug, job: doc });
+  const report = (d) => { try { onProgress?.(d); } catch { /* the caller's callback never breaks the wait */ } };
+  report(doc);
+  const deadline = now() + Math.max(0, Number(timeoutMs) || DEFAULT_ASYNC_TIMEOUT_MS);
+  let wait = retryAfterMs(res.headers, doc);
+  let failures = 0;
+  for (;;) {
+    if (now() + wait > deadline) {
+      throw new AsyncJobPendingError(`"${slug}" is still running (${jobState(doc) || "running"}${doc.stage ? `, ${doc.stage}` : ""}); collect it from ${jobUrl} (free) until it expires`, { jobUrl, slug, job: doc });
+    }
+    await sleep(wait);
+    let g;
+    try { g = await fetchImpl(jobUrl, { headers: { Accept: "application/json" } }); }
+    catch { g = null; }
+    if (!g || g.status >= 500 || g.status === 429) {
+      if (++failures >= MAX_POLL_FAILURES) throw new AsyncJobPendingError(`the job link for "${slug}" could not be read (${g ? `HTTP ${g.status}` : "network error"}); collect it from ${jobUrl}`, { jobUrl, slug, job: doc });
+      wait = retryAfterMs(g?.headers, doc);
+      continue;
+    }
+    if (g.status === 404 || g.status === 410) {
+      throw new AsyncJobPendingError(`the job for "${slug}" is ${g.status === 410 ? "expired" : "unknown"} at ${jobUrl}`, { jobUrl, slug, job: doc });
+    }
+    failures = 0;
+    try { doc = await g.json(); } catch { doc = {}; }
+    report(doc);
+    const st = jobState(doc);
+    if (st === "succeeded" || st === "failed") return responseFromJob(doc);
+    wait = retryAfterMs(g.headers, doc);
+  }
+}

package/index.js

@@ -16,16 +16,19 @@
 //   AGENT_KEY             hex private key of a funded EVM wallet (USDC on Base/Polygon/Arbitrum), optional
 //   SOLANA_AGENT_KEY      base58 (or JSON byte-array) secret key of a funded Solana wallet (USDC on Solana), optional
 //   AGENT402_TOOLS        comma-separated slugs to expose first-class (overrides default)
-//   AGENT402_MAX_PER_CALL refuse any single call priced above this many USD (e.g. 0.01)
+//   AGENT402_MAX_PER_CALL refuse any single call priced above this many USD (default 4; off disables)
 //   AGENT402_CREDITS_KEY  a prepaid credits key (a402_...) already issued (new credits are not on
 //                         sale); pays per successful call with no wallet
-//   AGENT402_BUDGET       hard cap on total USDC spent this session (e.g. 1.00)
+//   AGENT402_BUDGET       hard cap on total USD spent this session (opt-in: unset = no session cap)
 //   AGENT402_NETWORKS     restrict + order the chains to pay on (e.g. "robinhood" for USDG on
 //                         Robinhood Chain, "base,solana", or a raw CAIP-2 like eip155:4663), optional
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { quoteOf, guardSigning } from "./known-assets.js";
 import { parseNetworkPrefs, withNetworkPreference, distrustFetch } from "./networks.js";
 import { fetchDiscovery, discoveryFailure, getDiscoveryJson } from "./discovery.js";
+import { awaitJob, shouldRequestAsync, AsyncJobPendingError, DEFAULT_ASYNC_TIMEOUT_MS, jobState } from "./async-job.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -66,17 +69,49 @@ const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
 // list price only on a successful (200) call and returns X-Credits-Balance.
 const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
 const HAS_CREDITS = /^a402_[A-Za-z0-9_-]{32,64}$/.test(CREDITS_KEY);
+// Slow paid routes (async.recommended on their /api/pricing row) are sent with
+// Prefer: respond-async and collected from their job link (./async-job.js).
+// AGENT402_ASYNC=off waits on the connection instead; =always uses a job on
+// every route that runs as one. AGENT402_ASYNC_TIMEOUT_MS bounds the wait.
+const ASYNC_MODE = (() => { const v = String(process.env.AGENT402_ASYNC || "auto").trim().toLowerCase(); return v === "off" || v === "false" ? false : v === "always" || v === "true" ? true : "auto"; })();
+const ASYNC_TIMEOUT_MS = Number(process.env.AGENT402_ASYNC_TIMEOUT_MS) > 0 ? Number(process.env.AGENT402_ASYNC_TIMEOUT_MS) : DEFAULT_ASYNC_TIMEOUT_MS;
 // Version comes from package.json, the serverInfo self-report drifted from
 // the published version once (0.11.5 vs 0.12.1) because this was a hardcoded
 // string bumped by hand. Reading the manifest makes drift impossible.
 const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
 
-// Spend controls, enforced BEFORE a payment is ever signed, so a confused or
-// runaway model cannot drain the wallet. Unset = unlimited (back-compat).
-const num = (v) => (v !== undefined && v !== "" && Number.isFinite(Number(v)) ? Number(v) : undefined);
-const MAX_PER_CALL = num(process.env.AGENT402_MAX_PER_CALL) ?? Infinity;
-const BUDGET = num(process.env.AGENT402_BUDGET) ?? Infinity;
+// Spend controls, enforced on the payment that is signed (see getPayFetch), so
+// a confused or runaway model cannot drain the wallet. The per-call cap is on
+// by default, at the dearest list price in the Agent402 catalog rounded up to
+// a whole dollar (mcp/test.js checks it still covers the catalog), and `off`
+// disables it; a malformed value reads as that default, never as off. The
+// session budget is opt-in: unset (or `off`) is no session cap, so a long
+// session is never refused by default.
+const DEFAULT_MAX_PER_CALL_USD = 4;
+const DEFAULT_BUDGET_USD = Infinity;
+const capFromEnv = (name, def) => {
+  const raw = String(process.env[name] ?? "").trim().toLowerCase();
+  if (raw === "") return def;
+  if (raw === "off") return Infinity;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 0) return n;
+  console.error(`[agent402-mcp] ${name}=${JSON.stringify(process.env[name])} is not a USD amount or "off"; using the default (${def === Infinity ? "no cap" : `$${def}`})`);
+  return def;
+};
+const MAX_PER_CALL = capFromEnv("AGENT402_MAX_PER_CALL", DEFAULT_MAX_PER_CALL_USD);
+const BUDGET = capFromEnv("AGENT402_BUDGET", DEFAULT_BUDGET_USD);
 let spentUsd = 0;
+// Wallet calls in flight, each holding what it may sign until it settles or
+// fails, so concurrent calls cannot each pass against the same budget. The
+// signing guard reads the one being signed from signCtx.
+const pendingSpend = new Set();
+const signCtx = new AsyncLocalStorage();
+const pendingUsd = (except = null) => { let t = 0; for (const e of pendingSpend) if (e !== except) t += e.usd; return t; };
+/** The most the payment being signed may ask for: the per-call cap and what is
+ *  left of the session budget after every other call in flight. */
+function signAllowance() {
+  return Math.max(0, Math.min(MAX_PER_CALL, BUDGET - spentUsd - pendingUsd(signCtx.getStore() || null)));
+}
 
 const DEFAULT_CURATED = [
   // Flagship demand set, keep aligned with src/mcp-flagship.js FLAGSHIP_SLUGS.
@@ -139,6 +174,7 @@ async function loadCatalog() {
       description: e.description,
       category: e.category,
       computePayable: !!e.computePayable,
+      async: e.async && typeof e.async === "object" ? e.async : null,
       inputSchema,
     });
   }
@@ -153,7 +189,17 @@ function getPayFetch() {
     const { x402Client } = await import("@x402/core/client");
     const { wrapFetchWithPayment } = await import("@x402/fetch");
     const client = new x402Client();
-    client.setSpendControls?.(false); // @x402/core 2.23+ defaults to a $1 pegged-assets-only cap; this package bounds spend itself
+    // This package's guard (./known-assets.js) holds every signature to
+    // AGENT402_MAX_PER_CALL and what is left of AGENT402_BUDGET, priced from
+    // known assets only. It replaces the library's default control, which
+    // allows only that library's default assets (so no USDG on Robinhood
+    // Chain) under a fixed $1 cap.
+    client.setSpendControls?.(false);
+    guardSigning(client, {
+      allowance: signAllowance,
+      onSign: (usd) => { const e = signCtx.getStore(); if (e) { e.usd = usd; e.signed = true; } },
+      onRefuse: (detail) => { const e = signCtx.getStore(); if (e) e.refusal = detail; },
+    });
     if (AGENT_KEY) {
       const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
       const { privateKeyToAccount } = await import("viem/accounts");
@@ -225,9 +271,12 @@ function walletRequiredText(tool) {
 // paths read the amount out of the 402 before spending anything.
 //
 // The preflight carries no payment header and no credits key, so it can only
-// ever draw an unpaid 402 - it never signs and never debits. Only run when a
-// ceiling is configured: with none, the number changes nothing and the round
-// trip is pure cost.
+// ever draw an unpaid 402 - it never signs and never debits. Only the credits
+// path sends one: it has no signing step, so the preflight's quote is what its
+// caps are checked against. The wallet path sends none; its caps hold at
+// signing (guardSigning in getPayFetch). Only run when a ceiling is
+// configured: with none, the number changes nothing and the round trip is
+// pure cost.
 const CAPS_CONFIGURED = Number.isFinite(MAX_PER_CALL) || Number.isFinite(BUDGET);
 
 /** The accepts array, at the top level or under the envelope keys sellers wrap it in. */
@@ -241,48 +290,31 @@ function acceptsOf(obj) {
   return null;
 }
 
-/** The MAXIMUM across accepts: the wallet picks which chain to settle on and
- *  this server cannot know which, so the only sound ceiling is the dearest
- *  offer. An entry we cannot price makes the whole quote unreadable (null),
- *  never a guess. */
-function usdFromAccepts(accepts) {
-  if (!Array.isArray(accepts) || !accepts.length) return null;
-  let maxUsd = null;
-  for (const a of accepts) {
-    // v2 names the base-unit amount `amount`; x402 v1 called it `maxAmountRequired`.
-    const atomic = Number(a && (a.amount ?? a.maxAmountRequired));
-    if (!Number.isFinite(atomic) || atomic < 0) return null;
-    // USDC is 6 decimals on every chain these rails settle; a wrong exponent is
-    // a 1000x pricing error, so an out-of-range hint reads as unreadable.
-    const declared = (a && a.extra && a.extra.decimals) ?? (a && a.decimals);
-    const decimals = declared == null ? 6 : Number(declared);
-    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 30) return null;
-    const usd = atomic / 10 ** decimals;
-    if (maxUsd == null || usd > maxUsd) maxUsd = usd;
-  }
-  return maxUsd;
-}
-
-/** The quoted price for this request, or `listUsd` when the 402 cannot be read.
+/** The quoted price for this request, or `listUsd` when no 402 can be read.
  *  x402 v2 carries the challenge base64 in the PAYMENT-REQUIRED header and
- *  leaves the body `{}`; v1 sellers put it in the body. Header first. */
+ *  leaves the body `{}`; v1 sellers put it in the body. Header first.
+ *
+ *  Each accept is priced from the known-asset table (./known-assets.js), never
+ *  from a decimals value the seller sends. The credits gate debits its own
+ *  quote, so the dearest known accept is the price. */
 async function quotedUsd(url, init, listUsd) {
-  if (!CAPS_CONFIGURED) return listUsd;
+  if (!CAPS_CONFIGURED) return { usd: listUsd };
+  let q = null;
   try {
     const pre = await ownFetch(url, init);
-    if (pre.status !== 402) return listUsd;
-    let quoted = null;
+    if (pre.status !== 402) return { usd: listUsd };
     const header = pre.headers.get("payment-required");
     if (header) {
-      try { quoted = usdFromAccepts(acceptsOf(JSON.parse(Buffer.from(header.trim(), "base64").toString("utf8")))); } catch { quoted = null; }
+      try { q = quoteOf(acceptsOf(JSON.parse(Buffer.from(header.trim(), "base64").toString("utf8")))); } catch { q = null; }
     }
-    if (quoted == null) {
+    if (!q) {
       let body = null; try { body = await pre.json(); } catch { body = null; }
-      quoted = usdFromAccepts(acceptsOf(body));
+      q = quoteOf(acceptsOf(body));
     }
-    // Larger of the two: an understated catalog must not lower the ceiling.
-    return quoted == null ? listUsd : Math.max(listUsd, quoted);
-  } catch { return listUsd; /* fail-open to the advertised price */ }
+  } catch { return { usd: listUsd }; /* no readable 402: the advertised price */ }
+  if (!q || q.max == null) return { usd: listUsd };
+  // Larger of the two: an understated catalog must not lower the ceiling.
+  return { usd: Math.max(listUsd, q.max) };
 }
 
 // A refused call's tool text. A 402 body from an x402 v2 seller may also carry
@@ -299,9 +331,35 @@ function failureText(status, text) {
   return JSON.stringify({ ...rest, status, paymentOptions: Array.isArray(accepts) ? accepts.length : 0, note: "The full offer is in the PAYMENT-REQUIRED header of this 402." });
 }
 
-async function callEndpoint(tool, args = {}) {
+/** A job's progress as MCP notifications/progress, when the caller asked for
+ *  progress (a progressToken on the tools/call). Progress only ever rises. */
+function progressNotifier(req, extra) {
+  const token = req?.params?._meta?.progressToken;
+  if (token === undefined || token === null || typeof extra?.sendNotification !== "function") return null;
+  let last = -1;
+  return (doc) => {
+    const pct = Number.isFinite(doc?.progress) ? Math.round(doc.progress * 100) : 0;
+    // MCP requires progress to increase with each notification.
+    if (pct <= last) return;
+    const value = pct;
+    last = value;
+    const eta = Number.isFinite(doc?.etaSeconds) ? `, about ${doc.etaSeconds} s left` : "";
+    const message = `${jobState(doc) || "running"}${doc?.stage ? `: ${doc.stage}` : ""}${doc?.steps ? ` (${doc.steps.done} of ${doc.steps.total} steps)` : ""}${doc?.progressEstimated ? " (estimated)" : ""}${eta}`;
+    extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: value, total: 100, message } }).catch(() => {});
+  };
+}
+
+function isRedirect(r) {
+  return r?.type === "opaqueredirect" || (r?.status >= 300 && r?.status < 400);
+}
+
+async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
   const url = new URL(`${BASE}${tool.path}`);
   const init = { method: tool.method, headers: { Accept: "application/json" } };
+  // A slow route runs as a job (./async-job.js): the paid call asks for one,
+  // and the job link is polled (free) until the answer is ready.
+  const asyncHeaders = shouldRequestAsync(tool.async, ASYNC_MODE) ? { Prefer: "respond-async" } : {};
+  const collect = (r) => awaitJob(r, { baseUrl: BASE, fetchImpl: ownFetch, timeoutMs: ASYNC_TIMEOUT_MS, onProgress, slug: tool.slug });
   if (tool.method === "GET") {
     for (const [k, v] of Object.entries(args)) {
       if (v === undefined || v === null) continue;
@@ -312,48 +370,89 @@ async function callEndpoint(tool, args = {}) {
     init.body = JSON.stringify(args);
   }
 
+  // A request that can carry a payment never follows a redirect: followed, it
+  // would pay another origin's 402, or forward a signature already made to
+  // another host, and return that host's answer as this tool's.
+  const paidInit = { ...init, redirect: "manual" };
+  const redirectRefusal = (r) => {
+    const loc = r.headers.get("location");
+    const to = loc ? new URL(loc, url).href : null;
+    return { content: [{ type: "text", text: `Refused: ${url.href} answered a paid call to "${tool.slug}" with HTTP ${r.status || "redirect"}${to ? ` pointing to ${to}` : ""}. Paid requests never follow redirects${to ? `; if that is the address you meant, set AGENT402_URL to ${new URL(to).origin}` : ""}.` }], isError: true };
+  };
+
   let res;
   if (!HAS_WALLET && HAS_CREDITS) {
     // Card credits: same budget guards as the wallet path, against the same
     // number - the credits gate holds and debits what the 402 quotes for THIS
     // body, not the route's list price.
     const listUsd = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
-    const price = await quotedUsd(url, init, listUsd);
+    const { usd: price } = await quotedUsd(url, paidInit, listUsd);
     if (price > MAX_PER_CALL) {
       return { content: [{ type: "text", text: `Refused: "${tool.slug}" is quoted $${price} for this request${price !== listUsd ? ` (list price ${tool.price})` : ""}, above the AGENT402_MAX_PER_CALL cap of $${MAX_PER_CALL}.` }], isError: true };
     }
     if (spentUsd + price > BUDGET) {
       return { content: [{ type: "text", text: `Refused: session budget exhausted ($${spentUsd.toFixed(4)} of $${BUDGET} spent; "${tool.slug}" is quoted $${price} for this request).` }], isError: true };
     }
-    res = await ownFetch(url, { ...init, headers: { ...init.headers, Authorization: `Bearer ${CREDITS_KEY}` } });
+    try {
+      const first = await ownFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders, Authorization: `Bearer ${CREDITS_KEY}` } });
+      if (isRedirect(first)) return redirectRefusal(first);
+      res = await collect(first);
+    }
+    catch (e) { if (e instanceof AsyncJobPendingError) { spentUsd += price; return pendingJobResult(tool, e); } throw e; }
     if (res.ok) spentUsd += price;
     if (res.status === 402) {
       let body = {}; try { body = await res.clone().json(); } catch { /* plain */ }
       return { content: [{ type: "text", text: `Credits refused for "${tool.slug}": ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""}. Top up at ${body.topup || `${BASE}/credits`}.` }], isError: true };
     }
   } else if (HAS_WALLET) {
-    // The wallet signs whatever the challenge asks for (vendor spend controls
-    // are off - this package bounds spend itself), so the cap is checked
-    // against that amount, read from the 402 before anything is signed.
-    const listUsd = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
-    const price = await quotedUsd(url, init, listUsd);
+    // The signing guard (installed on every key-built client, getPayFetch)
+    // holds the payment that is signed to the caps and refuses an asset it
+    // cannot price, so no unpaid preflight is sent: the paid request's own 402
+    // is the one quote, read once, at signing. The list price is checked here
+    // first only because it costs no request: the quote is never below it for
+    // the cap's purposes (an understated catalog must not lower the ceiling).
+    const price = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
     if (price > MAX_PER_CALL) {
       return {
-        content: [{ type: "text", text: `Refused without paying: "${tool.slug}" is quoted $${price} for this request${price !== listUsd ? ` (list price ${tool.price})` : ""}, above the AGENT402_MAX_PER_CALL cap of $${MAX_PER_CALL}. Raise the cap on this MCP server to allow it.` }],
+        content: [{ type: "text", text: `Refused without paying: "${tool.slug}" lists at ${tool.price}, above the AGENT402_MAX_PER_CALL cap of $${MAX_PER_CALL}. Raise the cap on this MCP server to allow it.` }],
         isError: true,
       };
     }
-    if (spentUsd + price > BUDGET) {
+    const inFlight = pendingUsd();
+    if (spentUsd + inFlight + price > BUDGET) {
       return {
-        content: [{ type: "text", text: `Refused without paying: session budget exhausted ($${spentUsd.toFixed(4)} of $${BUDGET} spent; "${tool.slug}" is quoted $${price} for this request). Restart the MCP server or raise AGENT402_BUDGET.` }],
+        content: [{ type: "text", text: `Refused without paying: session budget exhausted ($${spentUsd.toFixed(4)} of $${BUDGET} spent${inFlight ? `, $${inFlight.toFixed(4)} in flight` : ""}; "${tool.slug}" lists at ${tool.price}). Restart the MCP server or raise AGENT402_BUDGET.` }],
         isError: true,
       };
     }
     const payFetch = await getPayFetch();
-    res = await payFetch(url, init);
-    // Count spend when the server confirms settlement (payment receipt header),
-    // falling back to any 2xx, conservative in the buyer's favor.
-    if (res.headers.get("payment-response") || res.headers.get("x-payment-response") || res.ok) spentUsd += price;
+    // Held until the call settles or fails; the guard replaces `usd` with the
+    // amount it lets the wallet sign.
+    const entry = { usd: price, signed: false, refusal: null };
+    pendingSpend.add(entry);
+    try {
+      const first = await signCtx.run(entry, () => payFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders } }));
+      if (isRedirect(first)) {
+        pendingSpend.delete(entry);
+        // A signature already sent leaves that payment's outcome unknown, so
+        // it counts against the session budget.
+        if (entry.signed) spentUsd += entry.usd;
+        return redirectRefusal(first);
+      }
+      res = await collect(first);
+    }
+    catch (e) {
+      pendingSpend.delete(entry);
+      // Still running past the wait: it may yet settle, so it counts as spent.
+      if (e instanceof AsyncJobPendingError) { if (entry.signed) spentUsd += entry.usd; return pendingJobResult(tool, e); }
+      if (entry.refusal) return signingRefusal(tool, entry.refusal);
+      throw e;
+    }
+    pendingSpend.delete(entry);
+    // Count spend when a payment was signed and the server confirms settlement
+    // (payment receipt header), falling back to any 2xx, conservative in the
+    // buyer's favor.
+    if (entry.signed && (res.headers.get("payment-response") || res.headers.get("x-payment-response") || res.ok)) spentUsd += entry.usd;
   } else if (tool.computePayable) {
     // No wallet: pay with compute up front, solving before the call skips the
     // 402 round-trip entirely (challenges are single-use and tool-scoped).
@@ -382,9 +481,33 @@ async function callEndpoint(tool, args = {}) {
   let parsed;
   try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
   const structured = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { result: parsed };
+  // A binary answer collected from a job arrives as { contentType, encoding: "base64", data }.
+  if (structured.encoding === "base64" && typeof structured.data === "string" && /^image\//.test(String(structured.contentType || ""))) {
+    return {
+      content: [{ type: "image", data: structured.data, mimeType: String(structured.contentType) }],
+      structuredContent: { slug: tool.slug, result: { contentType: structured.contentType, encoding: "base64", note: "Binary payload is in the image content block" } },
+    };
+  }
   return { content: [{ type: "text", text }], structuredContent: structured };
 }
 
+/** The tool result for a payment the signing guard refused. */
+function signingRefusal(tool, d) {
+  const text = d.reason === "unknown-asset"
+    ? `Refused without paying: "${tool.slug}" asked to be paid in an asset this server cannot price (USDC or USDG on a known network), so nothing was signed.`
+    : `Refused without paying: "${tool.slug}" asked for $${d.priceUsd} on the paid request, above the $${Number(d.allowanceUsd.toFixed(6))} this server may sign (AGENT402_MAX_PER_CALL ${MAX_PER_CALL === Infinity ? "off" : `$${MAX_PER_CALL}`}, AGENT402_BUDGET ${BUDGET === Infinity ? "off" : `$${BUDGET}`} with $${spentUsd.toFixed(4)} spent). Nothing was signed.`;
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+/** The tool result for a job still running when the wait ended. */
+function pendingJobResult(tool, e) {
+  return {
+    content: [{ type: "text", text: `${tool.slug}: ${e.message}. The call was paid for as a job; payment settles only if the answer is delivered. Poll the job link (free, no payment) for the answer.` }],
+    structuredContent: { slug: tool.slug, pending: true, jobUrl: e.jobUrl || null, job: e.job || null },
+    isError: true,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Tool search over the full catalog (for everything not exposed first-class).
 // Front-door phrase boosts mirror src/find.js applyFrontDoorTerms so stdio
@@ -543,7 +666,7 @@ async function ensureCatalog() {
     log(`Could not load the catalog from ${BASE}: ${err.message}: next read in ${CATALOG_RETRY_MS / 1000}s`);
   }
 }
-const withCatalog = (handler) => async (req) => { await ensureCatalog(); return handler(req); };
+const withCatalog = (handler) => async (req, extra) => { await ensureCatalog(); return handler(req, extra); };
 
 server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
   const SAFE = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -674,7 +797,7 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
   return { tools };
 }));
 
-server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req) => {
+server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) => {
   const { name: rawName, arguments: args = {} } = req.params;
   const name = resolveListedName(rawName);
   const overBound = toolInputBoundRefusal(rawName, args);
@@ -907,7 +1030,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req) => {
       if (!tool) return { content: [{ type: "text", text: `External routing (${slug}) is not in the catalog from ${BASE} yet. It may be rolling out; retry shortly.` }], isError: true };
       // Body matches the route-execute input schema; include:"external" is what
       // pays an OUTSIDE seller (vs this host's catalog). Paid via callEndpoint.
-      return await callEndpoint(tool, { task, include: "external", maxUsd, ...(args.params && typeof args.params === "object" ? { params: args.params } : {}) });
+      return await callEndpoint(tool, { task, include: "external", maxUsd, ...(args.params && typeof args.params === "object" ? { params: args.params } : {}) }, { onProgress: progressNotifier(req, extra) });
     }
     // Curated tools are exposed verb_noun for tools/list consistency, but the
     // real slug is kebab, accept exposed name, plain snake, or raw slug.
@@ -920,7 +1043,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req) => {
     if (!tool) {
       return { content: [{ type: "text", text: `Unknown tool slug "${wanted}". Use catalog.search to find the right slug.` }], isError: true };
     }
-    const out = await callEndpoint(tool, name === "catalog.call" ? (args.params ?? {}) : args);
+    const out = await callEndpoint(tool, name === "catalog.call" ? (args.params ?? {}) : args, { onProgress: progressNotifier(req, extra) });
     // call_tool: wrap structuredContent in {slug, result} to match META_OUTPUT_SCHEMAS["catalog.call"]
     // while keeping content text as the native tool JSON.
     if (name === "catalog.call" && !out.isError && out.structuredContent) {

package/known-assets.js

@@ -0,0 +1,120 @@
+// Known payment assets, and the USD value of an x402 accept priced from them.
+//
+// An x402 "exact" signer signs the accept's raw base-unit `amount` for the
+// accept's `asset`. A spending cap therefore has to price that amount with the
+// asset's real decimals, and a decimals hint the seller sends beside it (for
+// example `extra.decimals`) is not evidence of anything. So the price of an
+// accept comes from this table alone: the stablecoins each network settles on
+// the Agent402 rails, with their on-chain decimals. An accept whose
+// (network, asset) pair is not in the table cannot be priced, and a buyer with
+// a cap does not sign it.
+//
+// The same file ships in agent402-client, agent402-mcp and agent402-openclaw;
+// the parent repo's scripts/test-known-assets.js keeps the copies identical and
+// checks the table against the assets the server offers.
+
+/** network (CAIP-2) -> the assets a buyer may price there. */
+export const KNOWN_ASSETS = Object.freeze({
+  // EVM: USDC (native Circle) unless named otherwise.
+  "eip155:8453": [{ asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, symbol: "USDC" }], // Base
+  "eip155:84532": [{ asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", decimals: 6, symbol: "USDC" }], // Base Sepolia
+  "eip155:137": [{ asset: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", decimals: 6, symbol: "USDC" }], // Polygon
+  "eip155:42161": [{ asset: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", decimals: 6, symbol: "USDC" }], // Arbitrum
+  "eip155:143": [{ asset: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", decimals: 6, symbol: "USDC" }], // Monad
+  "eip155:42220": [{ asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", decimals: 6, symbol: "USDC" }], // Celo
+  "eip155:43114": [{ asset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6, symbol: "USDC" }], // Avalanche
+  "eip155:1329": [{ asset: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392", decimals: 6, symbol: "USDC" }], // Sei
+  "eip155:10": [{ asset: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", decimals: 6, symbol: "USDC" }], // Optimism
+  "eip155:5042": [{ asset: "0x3600000000000000000000000000000000000000", decimals: 6, symbol: "USDC" }], // Arc
+  "eip155:4663": [{ asset: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", decimals: 6, symbol: "USDG" }], // Robinhood Chain
+  // Solana: the USDC mint.
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [{ asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", decimals: 6, symbol: "USDC" }],
+  "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": [{ asset: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", decimals: 6, symbol: "USDC" }], // devnet
+  // Stellar: the USDC Stellar Asset Contract (7 decimals on Stellar).
+  "stellar:pubnet": [{ asset: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75", decimals: 7, symbol: "USDC" }],
+  // Algorand: USDC is ASA 31566704.
+  "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=": [{ asset: "31566704", decimals: 6, symbol: "USDC" }],
+});
+
+const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+// EVM addresses compare without case (checksum casing is presentation);
+// base58, Stellar and Algorand identifiers compare exactly.
+const sameAsset = (a, b) => (EVM_ADDRESS.test(a) && EVM_ADDRESS.test(b) ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+/** The table entry for (network, asset), or null when it is not a known asset. */
+export function knownAsset(network, asset) {
+  if (typeof network !== "string" || typeof asset !== "string" || !asset) return null;
+  const list = KNOWN_ASSETS[network];
+  if (!list) return null;
+  return list.find((e) => sameAsset(e.asset, asset)) || null;
+}
+
+/** The USD value of one accept: its base-unit amount (`amount` in x402 v2,
+ *  `maxAmountRequired` in v1) over the KNOWN decimals of its asset. null when
+ *  the asset is not known or the amount is not a whole number of base units. */
+export function acceptUsd(accept) {
+  if (!accept || typeof accept !== "object") return null;
+  const raw = accept.amount ?? accept.maxAmountRequired;
+  if (raw == null || !/^\d+$/.test(String(raw))) return null;
+  const entry = knownAsset(accept.network, accept.asset);
+  if (!entry) return null;
+  return Number(raw) / 10 ** entry.decimals;
+}
+
+/** The USD values of a 402's accepts: `max` and `min` over the accepts that can
+ *  be priced, and `unknown`, the count that cannot. null when there are none. */
+export function quoteOf(accepts) {
+  if (!Array.isArray(accepts) || !accepts.length) return null;
+  let max = null, min = null, unknown = 0;
+  for (const a of accepts) {
+    const usd = acceptUsd(a);
+    if (usd == null) { unknown++; continue; }
+    if (max == null || usd > max) max = usd;
+    if (min == null || usd < min) min = usd;
+  }
+  return { max, min, unknown, total: accepts.length };
+}
+
+/** Enforce a USD allowance at signing on an @x402/core x402Client.
+ *
+ *  `allowance()` is the most this buyer may sign for the payment being built
+ *  (a per-call cap, a remaining budget, or the smaller of the two; Infinity
+ *  for none). A registered policy drops every accept that cannot be priced or
+ *  is over the allowance, so the client selects among the ones that fit, and a
+ *  hook before payload creation checks the selected accept again and passes
+ *  its USD value to `onSign`. A refusal throws (from the policy) or aborts
+ *  (from the hook) before any signature exists; `onRefuse` hears why first. */
+export function guardSigning(client, { allowance, onSign = null, onRefuse = null }) {
+  if (!client || typeof client.registerPolicy !== "function" || typeof client.onBeforePaymentCreation !== "function") {
+    throw new TypeError("guardSigning needs an @x402/core x402Client (registerPolicy and onBeforePaymentCreation)");
+  }
+  if (typeof allowance !== "function") throw new TypeError("guardSigning needs an allowance() function");
+  const refuse = (detail) => { try { onRefuse?.(detail); } catch { /* the refusal stands */ } return detail; };
+  client.registerPolicy((version, accepts) => {
+    const cap = allowance();
+    const kept = accepts.filter((a) => { const usd = acceptUsd(a); return usd != null && usd <= cap; });
+    if (!kept.length) {
+      const q = quoteOf(accepts);
+      const d = refuse({ reason: q && q.min != null ? "over-allowance" : "unknown-asset", priceUsd: q ? q.min : null, allowanceUsd: cap });
+      throw new Error(d.reason === "unknown-asset"
+        ? "spending guard: no payment option is in a known asset, so none can be priced; nothing was signed"
+        : `spending guard: the cheapest payment option asks $${d.priceUsd}, above the $${cap} this buyer may sign; nothing was signed`);
+    }
+    return kept;
+  });
+  client.onBeforePaymentCreation(async ({ selectedRequirements: r }) => {
+    const usd = acceptUsd(r);
+    const cap = allowance();
+    if (usd == null) {
+      refuse({ reason: "unknown-asset", priceUsd: null, allowanceUsd: cap });
+      return { abort: true, reason: "spending guard: the selected payment option is not in a known asset; nothing was signed" };
+    }
+    if (usd > cap) {
+      refuse({ reason: "over-allowance", priceUsd: usd, allowanceUsd: cap });
+      return { abort: true, reason: `spending guard: the selected payment option asks $${usd}, above the $${cap} this buyer may sign; nothing was signed` };
+    }
+    onSign?.(usd, r);
+    return undefined;
+  });
+  return client;
+}

package/networks.js

@@ -17,6 +17,7 @@ export const NETWORK_CAIP2 = {
   arbitrum: "eip155:42161",
   "base-sepolia": "eip155:84532",
   robinhood: "eip155:4663",
+  arc: "eip155:5042",
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-mcp",
-  "version": "0.13.15",
+  "version": "0.13.17",
   "mcpName": "io.github.MikeyPetrillo/agent402",
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "homepage": "https://agent402.tools",
@@ -9,13 +9,15 @@
     "url": "git+https://github.com/MikeyPetrillo/Agent402.git",
     "directory": "mcp"
   },
-  "description": "Agent402 MCP server: 500+ pay-per-call tools + skill packs for AI agents over x402 (USDC or USDG on 12 chains) or MPP on the same 402, or free via proof-of-work - the applied layer of Agentic Finance. Catalog: browser, web search + cited answers, PDFs, OCR, images, LLM inference, image generation, code execution, STT, embeddings, live financial/crypto/macro data, SEC EDGAR filings, deterministic stats & forecasting, compression, payments. Open source, self-hostable.",
+  "description": "Agent402 MCP server: 500+ pay-per-call tools + skill packs for AI agents over x402 (USDC or USDG on 13 chains) or MPP on the same 402, or free via proof-of-work - the applied layer of Agentic Finance. Catalog: browser, web search + cited answers, PDFs, OCR, images, LLM inference, image generation, code execution, STT, embeddings, live financial/crypto/macro data, SEC EDGAR filings, deterministic stats & forecasting, compression, payments. Open source, self-hostable.",
   "type": "module",
   "bin": {
     "agent402-mcp": "index.js"
   },
   "files": [
     "index.js",
+    "async-job.js",
+    "known-assets.js",
     "networks.js",
     "discovery.js",
     "output-schemas.js",
@@ -56,6 +58,7 @@
     "multi-chain",
     "monad",
     "celo",
+    "arc",
     "avalanche",
     "sei",
     "optimism",