agent402-client 0.8.14 → 0.8.16

package/README.md

@@ -68,7 +68,7 @@ registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.AGENT_K
 const payFetch = wrapFetchWithPayment(fetch, client);
 
 const a = new Agent402({ fetch: payFetch });
-const article = await a.call("extract", { url: "https://example.com/article" });
+const article = await a.call("extract", { url: "https://agent402.tools/guides/x402-in-5-minutes" });
 ```
 
 ## Prepaid credits (keys already issued)
@@ -182,18 +182,49 @@ const { window, asOf, results, totalSellers } = await a.topSellers({ limit: 10 }
 await a.topSellers({ sort: "calls", include: "all" });
 ```
 
+## Slow routes run as jobs
+
+Reports, video and the premium image take from about 40 seconds to a few
+minutes, longer than many HTTP clients wait. Their `/api/pricing` row carries
+`async.recommended` with `expectedSeconds` and `maxSeconds`. For those routes
+`call()` sends the paid request with `Prefer: respond-async`: the server answers
+`202` with a job link at once, and the SDK polls `GET /api/jobs/{id}` (free),
+waiting `Retry-After` seconds between polls, until the job has succeeded or
+failed (it reads the job's `state` and falls back to its `status`, working,
+completed or failed, on a server that sends only that). Payment settles only on
+the delivered answer, so a failed job is a
+failed call and its spend is released.
+
+```js
+const a = new Agent402({
+  fetch: payFetch,
+  onProgress: (job) => console.log(job.status, job.stage, job.progress, job.etaSeconds),
+  asyncTimeoutMs: 10 * 60_000,
+});
+const report = await a.call("research", { query: "x402 adoption" });
+```
+
+A job still running when `asyncTimeoutMs` ends throws `AsyncJobPendingError`
+with `jobUrl`; collect it later with `await a.collectJob(err.jobUrl)`. Its price
+stays counted against your spending caps, because the answer may still be
+delivered and settled. Pass `respondAsync: false` (constructor or call) to wait
+on the connection instead, or `respondAsync: true` to use a job on every route
+that runs as one.
+
 ## API
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, maxResponseBytes?, outputValidator? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `creditsKey` is a prepaid card-credits key (`a402_...`) used for paid tools when no `fetch` is given; `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below); `maxResponseBytes` (default 32MB, `null` to disable) refuses an oversized response body before it is parsed; `outputValidator` binds a caller-supplied delivery check |
+| `new Agent402({ baseUrl?, fetch?, x402Client?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, maxResponseBytes?, outputValidator?, respondAsync?, asyncTimeoutMs?, onProgress? })` | `fetch` is your x402- or MPP-wrapped fetch for paid tools (optional); `x402Client` is the `@x402/core` client that `fetch` wraps, so the caps are enforced on the payment that is signed (see below); `creditsKey` is a prepaid card-credits key (`a402_...`) used for paid tools when no `fetch` is given; `cache` (default `true`) memoizes deterministic results; the three USD caps set optional spending limits (see below); `maxResponseBytes` (default 32MB, `null` to disable) refuses an oversized response body before it is parsed; `outputValidator` binds a caller-supplied delivery check; `respondAsync` (default `"auto"`), `asyncTimeoutMs` (default 15 minutes) and `onProgress` control slow routes run as jobs (see above) |
 | `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools on **this host** (route, price, schema, example) |
 | `await a.route(task, { k?, include?, network? })` | Cross-seller Smart Order Router: rank eligible/routable seller rows from the host's current index (free, read-only; opaque results may include server-reported `executeVia`) |
 | `await a.findWorkflows(task, { k = 2 })` | Resolve a task to matching multi-tool workflow templates (skill packs) |
 | `await a.getWorkflowPrompt(slug, args)` | Fetch the rendered prompt messages for a skill pack with arguments substituted in |
 | `await a.topSellers({ limit?, sort?, include? })` | Live x402 leaderboard: which sellers are settling the most USDC (primarily on Base) in the last ~24h (free, no payment) |
-| `await a.call(slug, params, { idempotencyKey?, cache?, maxResponseBytes?, outputValidator? })` | Call a tool; auto-pays (PoW for free tools; your payment `fetch` or the credits key for wallet-only); returns the JSON result |
+| `await a.call(slug, params, { idempotencyKey?, cache?, maxResponseBytes?, outputValidator?, respondAsync?, asyncTimeoutMs?, onProgress? })` | Call a tool; auto-pays (PoW for free tools; your payment `fetch` or the credits key for wallet-only); a slow route runs as a job and is collected for you; returns the JSON result |
+| `await a.collectJob(jobUrl, { timeoutMs?, onProgress? })` | Collect a job link (from `AsyncJobPendingError.jobUrl`) until it has the answer |
 | `Agent402.solvePow(pow)` | Solve a proof-of-work challenge object → an `X-Pow-Solution` value |
+| `a.guardX402Client(client)` | Enforce this client's caps on every payment the given `@x402/core` client signs (the same as passing `x402Client`); returns the client |
 | `a.spendingSummary()` | Rolling-24h paid spend so far: `{ dailyUsd, calls, byHost, limits }` |
 | `a.clearCache()` | Drop the in-memory result cache |
 
@@ -276,8 +307,13 @@ call that would exceed one is **refused before any payment is signed** (it throw
 ```js
 import { Agent402, SpendingLimitError } from "agent402-client";
 
+const client = new x402Client();
+registerExactEvmScheme(client, { signer });
+const payFetch = wrapFetchWithPayment(fetch, client);
+
 const a = new Agent402({
   fetch: payFetch,
+  x402Client: client,    // the caps are enforced on the payment that is signed
   maxPerCallUsd: 0.05,   // reject any single call priced above $0.05
   dailyLimitUsd: 5,      // rolling-24h ceiling across all sellers
   maxPerHostUsd: 1,      // rolling-24h ceiling per seller host
@@ -296,16 +332,33 @@ that later fails byte, JSON, or output validation remains settled spend. Free
 proof-of-work calls are never counted. Omit a cap (or leave it `null`) for no
 limit; with none set, behavior is unchanged.
 
-**What the caps check.** When a cap is set, the client preflights the `402` and
-checks the ceiling against the **larger** of the advertised price (from the
-seller's `/api/pricing`) and the amount the `402` challenge actually quotes - so a
-server that under-advertises and then quotes more in the `402` is refused *before*
-your wallet fetch signs anything. If the `402` can't be read (FREE_MODE, or an
-unrecognized challenge shape) it falls back to the advertised price rather than
-block a legitimate payment. Caps hold under **concurrency** too: each call reserves
-its amount synchronously, so N simultaneous calls can't each pass against the same
-pre-commit total. (The `402` amount is derived assuming stablecoin settlement -
-`atomic / 10^decimals ≈ USD` - which matches x402's USDC/USDG rails.)
+**Caps are enforced on the payment that is signed.** Pass the `x402Client` your
+`fetch` wraps (or call `a.guardX402Client(client)`) and the client registers a
+policy on it: every payment option that asks more than the per-call cap, or more
+than is left of the rolling caps, is dropped before the x402 client picks one,
+and the picked one is checked again just before it is signed. A refusal there is
+a `SpendingLimitError` with `atSigning: true`, and nothing is signed. The ledger
+books the amount actually signed.
+
+**The one advisory mode.** A pre-wrapped payment `fetch` given without its
+`x402Client` is the only mode where the caps are advisory: they are checked on
+an unpaid preflight of the `402`, before your wallet fetch runs, but not on the
+`402` that fetch then signs. The client logs a one-time warning when caps are
+set in this mode. The adapters built on this client (agent402-agentkit,
+elizaos-plugin-agent402) construct their own x402 client and pass it, so their
+caps hold at signing by default.
+
+**How a quote is priced.** An x402 signer signs the option's raw base-unit
+`amount`, so each option is priced from a built-in table of known assets per
+network (`KNOWN_ASSETS`: USDC on each Agent402 rail, USDG on Robinhood Chain,
+with their on-chain decimals), never from a decimals value the seller sends. An
+option in an asset outside the table cannot be priced, and a capped wallet never
+signs it. When a cap is set, the client preflights the `402` and checks the
+ceiling against the **larger** of the advertised price (from the seller's
+`/api/pricing`) and the amount the `402` quotes; if no `402` comes back
+(FREE_MODE) it checks the advertised price. Caps hold under **concurrency** too:
+each call reserves its amount synchronously, so N simultaneous calls can't each
+pass against the same pre-commit total.
 
 - **Zero dependencies** for the free/proof-of-work path (uses `node:crypto`).
 - **Non-custodial:** paid settlement is your `@x402/fetch` / `mppx` fetch + wallet (or a prepaid credits key you bought); this client never sees a private key.
@@ -325,7 +378,7 @@ import { wrapFetchWithPayment } from "@x402/fetch";
 
 const client = new x402Client();
 registerExactEvmScheme(client, { signer });
-withNetworkPreference(client, ["robinhood"]);   // or ["base","solana"], or ["eip155:4663"]
+withNetworkPreference(client, ["robinhood"]);   // or ["base","solana"], or ["eip155:4663"], or ["eip155:5042"] for Arc
 const payFetch = wrapFetchWithPayment(fetch, client);
 ```
 
@@ -351,6 +404,17 @@ const payFetch = wrapFetchWithPayment(fetch, client);
 Pairs with `maxPerCallUsd` / `dailyLimitUsd` (how much) and
 `withNetworkPreference` (which chain).
 
+## Paid calls never follow redirects
+
+A request that can carry a payment or a credits key is sent with
+`redirect: "manual"`. If it is answered with a redirect, the call throws
+`PaymentRedirectError` (`.location` is where it pointed) and nothing more is
+signed, so a redirect can never draw a payment to another host or carry a
+signature to one. A signature already sent before the redirect stays counted
+against your caps. Point `baseUrl` at the address that serves the routes
+directly (`https://agent402.tools`, not `www.` or `http://`); the error names
+the origin to use.
+
 ## Distrusted certificate authorities (`distrustFetch`)
 
 Since 0.8.14 the SDK's own requests refuse a TLS chain that passes through one

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 mcp/async-job.js (agent402-mcp).
+
+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

@@ -18,14 +18,19 @@
 //   // paid tools: pass an x402-wrapped fetch (your wallet signs)
 //   const a = new Agent402({ fetch: payFetch });
 import { createHash, randomBytes } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { quoteOf, guardSigning } from "./known-assets.js";
+export { KNOWN_ASSETS, knownAsset, acceptUsd } from "./known-assets.js";
 import { distrustFetch } from "./tls-distrust.js";
 export { distrustFetch, distrustDispatcher, distrustCheckServerIdentity, DISTRUSTED_SPKI_SHA256 } from "./tls-distrust.js";
+import { awaitJob, shouldRequestAsync, AsyncJobPendingError, DEFAULT_ASYNC_TIMEOUT_MS } from "./async-job.js";
+export { AsyncJobPendingError } from "./async-job.js";
 
 // Keep in lockstep with package.json. Every request the SDK issues carries
 // `User-Agent: agent402-client/<version>` - a standard header, no extra
 // network calls - so a seller can attribute traffic (and settled payments)
 // to this SDK. Product token only; nothing about the caller rides along.
-const VERSION = "0.8.14";
+const VERSION = "0.8.16";
 const USER_AGENT = `agent402-client/${VERSION}`;
 // 32MB: about a hundred times any realistic response from this catalog (the
 // largest is a base64 image at a few MB), so it cannot break a legitimate
@@ -62,6 +67,16 @@ async function shedRetryWaitMs(r, maxWaitMs = DISCOVERY_MAX_WAIT_MS) {
 
 const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// A pre-wrapped payment fetch with no x402Client is the one mode where the caps
+// are checked on an unpaid preflight only, not on the payment that is signed.
+// Said once per process, on the first capped paid call in that mode.
+let advisoryCapsWarned = false;
+function warnAdvisoryCaps() {
+  if (advisoryCapsWarned) return;
+  advisoryCapsWarned = true;
+  console.warn("[agent402-client] spending caps are set with a pre-wrapped payment fetch and no x402Client, so they are checked on a preflight of the 402 only, not on the payment that is signed. Pass { x402Client } (the client your fetch wraps) to enforce them at signing.");
+}
+
 export class Agent402 {
   /**
    * @param {object} [opts]
@@ -74,6 +89,8 @@ export class Agent402 {
    * @param {number} [opts.maxPerCallUsd]    hard ceiling on a single paid call (USD); over → SpendingLimitError before paying
    * @param {number} [opts.dailyLimitUsd]    hard ceiling on rolling-24h paid spend (USD)
    * @param {number} [opts.maxPerHostUsd]    hard ceiling on rolling-24h paid spend to one seller host (USD)
+   * @param {object} [opts.x402Client]       the @x402/core x402Client your `fetch` wraps: the caps are then
+   *                                         enforced on the payment that is signed (see guardX402Client)
    * @param {string} [opts.creditsKey]       a prepaid card-credits key (a402_...) already issued (new credits are
    *                                         not on sale) - pays wallet-only tools when no payFetch is given
    * @param {number|null} [opts.maxResponseBytes=33554432]
@@ -81,10 +98,23 @@ export class Agent402 {
    * @param {{id:string, validate:function}} [opts.outputValidator]
    *        Optional buyer-owned result validator. `id` namespaces cache entries;
    *        `validate` may return false or throw to reject delivery.
+   * @param {"auto"|boolean} [opts.respondAsync="auto"]
+   *        Slow paid routes (the catalog's `async.recommended`): "auto" sends the
+   *        paid call with Prefer: respond-async and polls the job link until the
+   *        answer is ready; true does it on every route that runs as a job; false
+   *        never (wait on the connection).
+   * @param {number} [opts.asyncTimeoutMs=900000] overall wait for a job; past it,
+   *        AsyncJobPendingError carries the job link to collect later
+   * @param {function} [opts.onProgress] called with each job document
+   *        ({ status, stage, progress, etaSeconds, ... }) while a job runs
    */
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = undefined, tlsDistrust = true,
-    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null,
-    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null } = {}) {
+    maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null, x402Client = null,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null,
+    respondAsync = "auto", asyncTimeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null } = {}) {
+    this.respondAsync = respondAsync;
+    this.asyncTimeoutMs = numOrNull(asyncTimeoutMs) ?? DEFAULT_ASYNC_TIMEOUT_MS;
+    this.onProgress = typeof onProgress === "function" ? onProgress : null;
     this.creditsKey = typeof creditsKey === "string" && /^a402_[A-Za-z0-9_-]{32,64}$/.test(creditsKey) ? creditsKey : null;
     if (fetchImpl === undefined) {
       fetchImpl = globalThis.fetch;
@@ -120,6 +150,11 @@ export class Agent402 {
       perHost: numOrNull(maxPerHostUsd),
       log: [], // [{ ts, host, usd }] - settled paid calls in the last 24h
     };
+    // The paid call being signed right now, so the signing guard can tell this
+    // call's own reservation from every other one (see guardX402Client).
+    this._signCtx = new AsyncLocalStorage();
+    this._guarded = false;
+    if (x402Client) this.guardX402Client(x402Client);
     // A response-size ceiling, enforced before parsing. See _readJson.
     this.maxResponseBytes = maxResponseBytes === null ? null : (numOrNull(maxResponseBytes) ?? DEFAULT_MAX_RESPONSE_BYTES);
     // Buyer-owned delivery policy. The callback stays entirely local and may
@@ -127,6 +162,53 @@ export class Agent402 {
     this.outputValidator = normalizeOutputValidator(outputValidator, "constructor");
   }
 
+  /**
+   * Enforce this client's spending caps on the payment that is signed.
+   *
+   * Register it on the x402Client your `fetch` wraps (or pass it as the
+   * `x402Client` option): every accept that cannot be priced from a known
+   * asset, or that asks more than the per-call cap or what is left of the
+   * rolling caps, is dropped before the client selects one, and the selected
+   * one is checked again just before its payload is built. The preflight read
+   * of the 402 still runs for a readable refusal, but the challenge that is
+   * signed is the one this guard sees, so the caps hold on the paid request's
+   * own 402 whatever the preflight said. Returns the client.
+   */
+  guardX402Client(client) {
+    guardSigning(client, {
+      allowance: () => this._signAllowance().cap,
+      onSign: (usd) => {
+        const ctx = this._signCtx.getStore();
+        if (!ctx) return;
+        ctx.signedUsd = usd;
+        if (ctx.reservation) ctx.reservation.usd = usd;
+      },
+      onRefuse: (detail) => {
+        const ctx = this._signCtx.getStore();
+        if (ctx) ctx.refusal = { ...detail, limit: this._signAllowance().limit };
+      },
+    });
+    this._guarded = true;
+    return client;
+  }
+
+  /** The most the payment being signed may ask for: the per-call cap and what
+   *  is left of the rolling-24h caps, net of every other call's reservation
+   *  (this call's own one is what is being replaced). */
+  _signAllowance() {
+    const s = this._spend;
+    const own = this._signCtx.getStore()?.reservation || null;
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const others = s.log.filter((e) => e.ts >= cutoff && e !== own);
+    const host = hostOf(this.baseUrl);
+    let cap = Infinity, limit = null;
+    const tighten = (value, name) => { if (value < cap) { cap = value; limit = name; } };
+    if (s.maxPerCall != null) tighten(s.maxPerCall, "maxPerCallUsd");
+    if (s.daily != null) tighten(s.daily - others.reduce((a, e) => a + e.usd, 0), "dailyLimitUsd");
+    if (s.perHost != null) tighten(s.perHost - others.filter((e) => e.host === host).reduce((a, e) => a + e.usd, 0), "maxPerHostUsd");
+    return { cap: Math.max(0, cap), limit };
+  }
+
   /**
    * Read a JSON body with a hard byte ceiling.
    *
@@ -215,7 +297,7 @@ export class Agent402 {
     const r = await this._discoveryGet("could not load catalog", "/api/pricing");
     const j = await r.json();
     const m = new Map();
-    for (const e of j.endpoints || []) m.set(e.slug, { method: e.method, path: e.path, computePayable: e.computePayable, price: e.price });
+    for (const e of j.endpoints || []) m.set(e.slug, { method: e.method, path: e.path, computePayable: e.computePayable, price: e.price, async: e.async && typeof e.async === "object" ? e.async : null });
     this._catalog = m;
     return m;
   }
@@ -341,7 +423,7 @@ export class Agent402 {
    * Call a tool by slug; pays automatically (PoW for free tools, x402 for
    * wallet-only) and returns the parsed JSON result.
    */
-  async call(slug, params = {}, { idempotencyKey, cache = true, maxResponseBytes, outputValidator } = {}) {
+  async call(slug, params = {}, { idempotencyKey, cache = true, maxResponseBytes, outputValidator, respondAsync, asyncTimeoutMs, onProgress } = {}) {
     // Resolve and validate the buyer-owned contract before catalog fetch,
     // credential access, payment preflight, or any other network action.
     const validator = outputValidator == null
@@ -376,12 +458,17 @@ export class Agent402 {
     const idem = idempotencyKey || (cache
       ? `a402-${createHash("sha256").update(`${this._idemSalt}:${cacheKey}`).digest("hex").slice(0, 24)}`
       : `a402-${createHash("sha256").update(`${cacheKey}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`);
-    const send = (extraHeaders = {}, useFetch = this.f) => {
+    const send = async (extraHeaders = {}, useFetch = this.f, { paid = false } = {}) => {
       // UA set here too (not only in the this.f wrapper) so the x402 payFetch
       // path - the one that settles real payments - always carries it.
       const headers = { "User-Agent": USER_AGENT, "Idempotency-Key": idem, ...extraHeaders };
       let url = `${this.baseUrl}${tool.path}`;
-      const init = { method: tool.method, headers };
+      // A request that can carry a payment never follows a redirect: followed,
+      // it would answer a 402 from another origin with a signature to that
+      // origin's payee, or forward a signature already made to another host,
+      // and deliver that host's answer as this route's. The redirect is
+      // refused with where it pointed, so an alias baseUrl is easy to fix.
+      const init = paid ? { method: tool.method, headers, redirect: "manual" } : { method: tool.method, headers };
       if (tool.method === "GET") {
         const qs = new URLSearchParams(Object.entries(params).map(([k, v]) => [k, typeof v === "object" ? JSON.stringify(v) : String(v)])).toString();
         if (qs) url += `?${qs}`;
@@ -389,8 +476,20 @@ export class Agent402 {
         headers["Content-Type"] = "application/json";
         init.body = JSON.stringify(params);
       }
-      return useFetch(url, init);
+      const r = await useFetch(url, init);
+      if (paid && (r?.type === "opaqueredirect" || (r?.status >= 300 && r?.status < 400))) throw new PaymentRedirectError(slug, url, r);
+      return r;
     };
+    const paidSend = (extraHeaders = {}, useFetch = this.f) => send(extraHeaders, useFetch, { paid: true });
+    // A slow route runs as a job: the paid call carries Prefer: respond-async,
+    // answers 202 with a job link, and the answer is collected from it (free)
+    // when ready. Payment still settles only on the delivered answer.
+    const asyncHeaders = shouldRequestAsync(tool.async, respondAsync ?? this.respondAsync) ? { Prefer: "respond-async" } : {};
+    const collect = (r) => awaitJob(r, {
+      baseUrl: this.baseUrl, fetchImpl: this.f, slug, sleep: this._sleep,
+      timeoutMs: numOrNull(asyncTimeoutMs) ?? this.asyncTimeoutMs,
+      onProgress: typeof onProgress === "function" ? onProgress : this.onProgress,
+    });
 
     // Wallet-only tool → settle in USDC via the provided x402 fetch.
     if (!tool.computePayable) {
@@ -407,22 +506,40 @@ export class Agent402 {
         // amount THIS request is quoted. Fail-open: a 402 we cannot read
         // (FREE_MODE / non-402 / unparseable) falls back to the advertised
         // price - never block a legitimate payment on a parse miss.
-        const usd = await this._quotedUsd(send, listUsd);
+        const guarded = this._guarded;
+        if (!guarded && this._spendCapsConfigured()) warnAdvisoryCaps();
+        const usd = await this._quotedUsd(paidSend, listUsd, { slug, mode: guarded ? "guarded" : "wallet" });
         // Reserve the amount synchronously (before the await) so concurrent calls
         // can't each observe the pre-commit total and collectively blow a rolling
-        // cap; release the reservation if the call doesn't settle.
-        const reservation = this._spendReserve(host, usd, slug, listUsd);
+        // cap; release the reservation if the call doesn't settle. With the
+        // signing guard on, the reservation is replaced by the amount actually
+        // signed, and a call that signed nothing spends nothing.
+        const reservation = this._spendReserve(host, usd, slug, listUsd, { always: guarded });
+        const ctx = { reservation, signedUsd: null, refusal: null };
+        const signedNothing = () => guarded && ctx.signedUsd == null;
         let settled = false;
         try {
-          const r = await send({}, this.payFetch);
+          const r = await collect(await this._signCtx.run(ctx, () => paidSend(asyncHeaders, this.payFetch)));
           if (!r.ok) throw this._fail(slug, r, await this._failureDetail(slug, r));
-          this._spendSettle(reservation); // confirm the reservation as settled spend
+          if (signedNothing()) this._spendRelease(reservation);
+          else this._spendSettle(reservation); // confirm the reservation as settled spend
           settled = true;
           return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: true });
         } catch (e) {
           // An invalid or oversized paid HTTP-success body is failed delivery,
-          // not a rollback of money that already moved.
-          if (!settled) this._spendRelease(reservation);
+          // not a rollback of money that already moved. A job still running
+          // past the wait may yet settle, so its reservation stands.
+          // A redirect after a signature was sent leaves that payment's outcome
+          // unknown, so it counts against the caps, like a job still running.
+          if ((e instanceof AsyncJobPendingError || e instanceof PaymentRedirectError) && !signedNothing()) this._spendSettle(reservation);
+          else if (!settled) this._spendRelease(reservation);
+          if (ctx.refusal) {
+            const d = ctx.refusal;
+            throw new SpendingLimitError(d.reason === "unknown-asset"
+              ? `refusing to pay for "${slug}" - no payment option it asked to sign is in a known asset, so none can be priced`
+              : `refusing to pay $${d.priceUsd} for "${slug}" - the payment it asked to sign is over ${d.limit || "the cap"} ($${d.allowanceUsd} left to sign)`,
+            { limit: d.limit || "signing", slug, priceUsd: d.priceUsd, cap: d.allowanceUsd, atSigning: true, cause: e });
+          }
           throw e;
         }
       }
@@ -436,11 +553,11 @@ export class Agent402 {
         // debit.
         const host = hostOf(this.baseUrl);
         const listUsd = parseUsd(tool.price);
-        const usd = await this._quotedUsd(send, listUsd);
+        const usd = await this._quotedUsd(paidSend, listUsd, { slug, mode: "credits" });
         const reservation = this._spendReserve(host, usd, slug, listUsd);
         let settled = false;
         try {
-          const r = await send({ Authorization: `Bearer ${this.creditsKey}` });
+          const r = await collect(await paidSend({ Authorization: `Bearer ${this.creditsKey}`, ...asyncHeaders }));
           if (r.status === 402) {
             const body = await r.json().catch(() => ({}));
             throw this._fail(slug, r, `call "${slug}" refused by credits: ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""} ${body.topup ? ` - top up at ${body.topup}` : body.topupNote ? ` - ${body.topupNote}` : ""}`);
@@ -449,7 +566,11 @@ export class Agent402 {
           this._spendSettle(reservation);
           settled = true;
           return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: true });
-        } catch (e) { if (!settled) this._spendRelease(reservation); throw e; }
+        } catch (e) {
+          if (e instanceof AsyncJobPendingError) this._spendSettle(reservation);
+          else if (!settled) this._spendRelease(reservation);
+          throw e;
+        }
       }
       const r = await send(); // no wallet - succeeds only on a FREE_MODE instance
       if (r.ok) return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: false });
@@ -468,6 +589,22 @@ export class Agent402 {
     return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: false });
   }
 
+  /**
+   * Collect a job link (AsyncJobPendingError.jobUrl, or a 202's Location) until
+   * it has the answer, and return the parsed answer. The link is free to poll
+   * and must be on this client's baseUrl origin.
+   */
+  async collectJob(jobUrl, { timeoutMs, onProgress, maxResponseBytes } = {}) {
+    const start = new Response(JSON.stringify({ statusUrl: String(jobUrl), pollIntervalSeconds: 1 }), { status: 202, headers: { "content-type": "application/json" } });
+    const r = await awaitJob(start, {
+      baseUrl: this.baseUrl, fetchImpl: this.f, slug: "job", sleep: this._sleep,
+      timeoutMs: numOrNull(timeoutMs) ?? this.asyncTimeoutMs,
+      onProgress: typeof onProgress === "function" ? onProgress : this.onProgress,
+    });
+    if (!r.ok) throw this._fail("job", r, await this._failureDetail("job", r));
+    return this._readJson(r, { maxBytes: maxResponseBytes, slug: "job", paid: true });
+  }
+
   async _assertOutput(slug, body, validator, { paid = false, cacheHit = false } = {}) {
     if (!validator) return body;
     try {
@@ -506,17 +643,38 @@ export class Agent402 {
    *  body. Only preflights when a ceiling is configured (it costs a round trip,
    *  and with no cap the number changes nothing). The preflight send carries no
    *  payment header and no credits key, so it can only ever draw a 402.
-   *  @returns {Promise<number>} the quoted amount, or `listUsd` when unreadable */
-  async _quotedUsd(send, listUsd) {
+   *
+   *  Each accept is priced from the table of known assets (./known-assets.js),
+   *  never from a decimals value the seller sends. `mode` says who signs:
+   *  "guarded" (the signing guard holds every signature to the caps, so the
+   *  cheapest known accept is what can be paid, and unknown ones are dropped
+   *  there), "wallet" (no guard: the wallet may sign any accept, so the dearest
+   *  one counts, and one that cannot be priced is refused here), or "credits"
+   *  (nothing is signed; the dearest known accept counts).
+   *  @returns {Promise<number>} the quoted amount, or `listUsd` when there is no readable 402 */
+  async _quotedUsd(send, listUsd, { slug = "", mode = "wallet" } = {}) {
     if (!this._spendCapsConfigured()) return listUsd;
+    let q = null;
     try {
       const pre = await send();
       if (pre?.status !== 402) return listUsd;
-      const quoted = await quoted402Usd(pre);
-      // Larger of the two: an understated catalog must not lower the ceiling
-      // the cap is checked against.
-      return quoted == null ? listUsd : Math.max(listUsd, quoted);
-    } catch { return listUsd; /* fail-open to the advertised price */ }
+      q = quoteOf(await challengeAccepts(pre));
+    } catch (e) {
+      // A redirect is refused here, before anything is reserved or signed.
+      if (e instanceof PaymentRedirectError) throw e;
+      return listUsd; /* no readable 402: the advertised price */
+    }
+    if (!q) return listUsd;
+    if (q.max == null || (mode === "wallet" && q.unknown > 0)) {
+      if (mode === "credits") return listUsd;
+      throw new SpendingLimitError(
+        `refusing to pay for "${slug}" - ${q.max == null ? "no" : "a"} payment option it offers is in an asset this client cannot price, and a capped wallet signs only what it can price${mode === "wallet" ? " (pass your x402Client to guard signing and pay the options it can price)" : ""}`,
+        { limit: "knownAsset", slug, priceUsd: null, unknownOptions: q.unknown });
+    }
+    const quoted = mode === "guarded" ? q.min : q.max;
+    // Larger of the two: an understated catalog must not lower the ceiling
+    // the cap is checked against.
+    return Math.max(listUsd, quoted);
   }
 
   /** Throw SpendingLimitError if paying `usd` to `host` now would break a cap.
@@ -594,9 +752,9 @@ export class Agent402 {
    *  concurrent calls account for each other's in-flight reservations instead of
    *  all passing against the same pre-commit total. Returns a reservation handle
    *  (or null for a $0 call). Throws SpendingLimitError before reserving if over. */
-  _spendReserve(host, usd, slug, listUsd = null) {
+  _spendReserve(host, usd, slug, listUsd = null, { always = false } = {}) {
     this._spendCheck(host, usd, slug, listUsd);
-    if (!(usd > 0)) return null;
+    if (!(usd > 0) && !always) return null;
     const entry = { ts: Date.now(), host, usd, pending: true };
     this._spend.log.push(entry);
     return entry;
@@ -633,6 +791,22 @@ export class Agent402 {
  *  time the body arrives, so a caller must be able to tell "I was charged and
  *  the seller sent something unusable" from "nothing happened". Losing that
  *  distinction would turn a refused response into a silently forgotten spend. */
+/** A request that could carry a payment was answered with a redirect, which
+ *  is never followed. `location` is where it pointed (null when the runtime
+ *  hides it, as a browser does for a manual redirect). */
+export class PaymentRedirectError extends Error {
+  constructor(slug, url, r) {
+    const location = r?.headers?.get?.("location") || null;
+    const to = location ? new URL(location, url).href : null;
+    super(`refusing to follow a redirect on a paid call to "${slug}": ${url} answered HTTP ${r?.status || "redirect"}${to ? ` pointing to ${to}` : ""}. Paid requests never follow redirects${to ? `; if that is the address you meant, set baseUrl to ${new URL(to).origin}` : ""}.`);
+    this.name = "PaymentRedirectError";
+    this.slug = slug;
+    this.status = r?.status ?? null;
+    this.location = to;
+    this.paid = false;
+  }
+}
+
 export class ResponseTooLargeError extends Error {
   constructor(size, cap, { slug, paid, source } = {}) {
     super(`response for "${slug}" is ${size} bytes, over the ${cap}-byte ceiling (${source}) - refused before parsing${paid ? "; this call WAS paid" : ""}`);
@@ -659,23 +833,30 @@ export class SpendingLimitError extends Error {
   }
 }
 
-// Parse the USD amount an x402 `402` challenge actually requires - the max across
-// the offered rails. x402 is stablecoin-settled (USDC/USDG), so
-// atomic / 10^decimals ≈ USD. Returns null if the body isn't a parseable 402
-// challenge, so the caller fails open to the advertised catalog price.
 /** The dearest amount a 402 asks for, in USD, or null when it cannot be read.
+ *
+ *  Each accept is priced from the known-asset table (./known-assets.js): the
+ *  base-unit amount over that asset's real decimals, never a decimals value
+ *  the seller sends. One accept that is not a known asset makes the whole
+ *  quote unreadable (null).
  *
  *  x402 v2 carries the challenge base64 in the `PAYMENT-REQUIRED` HEADER and
  *  leaves the body `{}`, so a body-only reader learns nothing from a stock v2
  *  seller and silently falls back to the catalog price. Header first, then the
  *  body (v1 sellers, and sellers that serve both). */
 export async function quoted402Usd(res) {
-  const header = res?.headers?.get?.("payment-required");
-  const fromHeader = usdFromAccepts(decodeChallengeHeader(header));
-  if (fromHeader != null) return fromHeader;
+  const q = quoteOf(await challengeAccepts(res));
+  // Every accept must be priceable: the wallet picks which one to sign.
+  return q && q.unknown === 0 ? q.max : null;
+}
+
+/** The accepts array of a 402, from the PAYMENT-REQUIRED header first, then the body. */
+async function challengeAccepts(res) {
+  const fromHeader = decodeChallengeHeader(res?.headers?.get?.("payment-required"));
+  if (fromHeader) return fromHeader;
   let body = null;
   try { body = await res.json(); } catch { body = null; }
-  return usdFromAccepts(acceptsOf(body));
+  return acceptsOf(body);
 }
 
 function decodeChallengeHeader(header) {
@@ -694,29 +875,6 @@ function acceptsOf(obj) {
   return null;
 }
 
-/** The MAXIMUM across accepts: the wallet picks which chain to settle on and
- *  this client cannot know which, so the only sound ceiling is the dearest
- *  offer. Any entry we cannot price returns null (unreadable, never a guess -
- *  the caller falls back to the advertised price). */
-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; an accept may say
-    // otherwise, and a wrong exponent is a 1000x pricing error, so a
-    // non-integer or out-of-range hint makes the whole quote 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;
-}
-
 function numOrNull(v) { if (v == null) return null; const n = Number(v); return Number.isFinite(n) && n >= 0 ? n : null; }
 function parseUsd(price) {
   if (typeof price === "number") return Number.isFinite(price) ? price : 0;
@@ -796,6 +954,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "description": "Agent402 buyer SDK: resolve a task to a tool across 500+ pay-per-call endpoints and call it with payment handled - free via proof-of-work, or over x402 or MPP (a stock mppx fetch works) with a wallet you keep; the buy side of Agentic Finance. Caching, idempotent retries (Idempotency-Key), non-custodial, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -9,6 +9,8 @@
   },
   "files": [
     "index.js",
+    "async-job.js",
+    "known-assets.js",
     "tls-distrust.js",
     "README.md"
   ],
@@ -41,6 +43,7 @@
     "tool-discovery",
     "smart-order-router",
     "robinhood-chain",
+    "arc",
     "usdg",
     "multi-chain",
     "agentic-finance",