agent402-client 0.8.18 → 0.8.20

package/README.md

@@ -94,6 +94,48 @@ credits call reserves its price like a wallet call). A payment `fetch` still win
 when both are given, and free pure-CPU tools keep settling with proof-of-work.
 The same Bearer header also reads the balance directly, e.g. `curl -H "Authorization: Bearer a402_..." https://agent402.tools/api/credits/balance`.
 
+## Paying from a Circle Gateway deposit (batched, no gas per call)
+
+Where a server offers it (Agent402 does on Arc and Base when its operator turns
+it on; `/api/pricing` says under `payment.gatewayNanopayments`), the 402 carries
+a second `exact` accept whose `extra.name` is `GatewayWalletBatched`. A buyer who
+deposited USDC into Circle Gateway once (an on-chain transfer through Circle's
+GatewayWallet contract; it pays gas once, and this SDK never deposits or
+withdraws) pays each call by signing the same EIP-3009 authorization under the
+Gateway domain the accept carries instead of the USDC contract's; Gateway
+verifies it against the deposit, settles it off chain and lands the batch on
+chain later. Pass the signer as the `gateway` option. Off by default: without it
+nothing changes. The SDK has no dependencies: install `viem` for
+`privateKeyToAccount`, or pass any EIP-712 signer with `address` and
+`signTypedData`.
+
+```js
+import { Agent402 } from "agent402-client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const signer = privateKeyToAccount(process.env.AGENT_KEY); // its address holds a Gateway deposit on Base or Arc
+const a = new Agent402({ gateway: { signer }, maxPerCallUsd: 0.05 });
+const out = await a.call("extract", { url: "https://agent402.tools/guides/x402-in-5-minutes" });
+```
+
+`signer` is any EIP-712 signer with `address` and `signTypedData` (a viem
+account). `gateway.networks` (chain names, as `withNetworkPreference` takes, for
+example `["arc"]`) limits which chains' batched accepts are signed; the default
+is any EVM chain the 402 offers one on. The caps are checked against the
+accept's own amount before anything is signed. A 402 with no batched accept this
+signer may pay (another seller, an identity-bound route, a route with a lasting
+effect) falls back to your payment `fetch` or `creditsKey` exactly as without the
+option, and with neither fails with a 402 that says so. A refusal for a short
+Gateway balance relays the server's hint and says to deposit first. A batched
+accept asking for a validity window past seven days and an hour
+(`GATEWAY_MAX_TIMEOUT_SECONDS`) is never signed: the signed authorization is a
+bearer claim on the deposit until its `validBefore`. For the same reason a
+batched authorization that was sent and refused stays valid until its
+`validBefore` and keeps counting against the caps; only a signer that throws
+before anything is sent releases the amount. The mechanism in full: [wiki: Circle Gateway](https://github.com/MikeyPetrillo/Agent402/wiki/Circle-Gateway).
+Two helpers are exported for a client of your own: `gatewayAcceptOf(accepts,
+networks?)` and `signGatewayPayment(accept, { signer, resource })`.
+
 ## Retries and double charges
 
 Every send carries an `Idempotency-Key`. By default it is derived from the
@@ -124,12 +166,11 @@ What the server does with it depends on how the call was paid:
   route with the same body, from its first answer inside the replay window,
   with no second settlement, and marks it `X-Replayed-Answer: 1` (identity-bound
   routes, routes with a lasting effect and streamed calls excepted).
-- **Circle Gateway batched option:** where the server offers it on Arc or Base,
-  the 402 carries a second accept whose `extra.name` is `GatewayWalletBatched`.
-  This package pays the plain accept on those networks (the stock x402 client
-  takes the first accept it can pay, and the plain one is first); the batched
-  one needs a client that signs under the Gateway domain against a Circle
-  Gateway deposit.
+- **Circle Gateway batched option:** a payment the server has not had confirmed
+  by Gateway yet is answered `402` with reason `settlement-pending`; the SDK
+  resends the same signed header after the server's `Retry-After` (never a new
+  signature), and past three resends throws `GatewayPendingError` with
+  `paymentHeader`, the header to resend later. See the section above.
 
 ## Workflows (skill packs)
 
@@ -228,7 +269,7 @@ that runs as one.
 
 | Method | What |
 |---|---|
-| `new Agent402({ baseUrl?, fetch?, x402Client?, creditsKey?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, payNetworks?, 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); `payNetworks` (for example `["base"]`, the names `withNetworkPreference` takes) tells the caps which chains a pre-wrapped `fetch` without an `x402Client` pays on, so a call is counted at the dearest option on those chains (when none of a 402's options is on them, the dearest of all counts); `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) |
+| `new Agent402({ baseUrl?, fetch?, x402Client?, creditsKey?, gateway?, cache?, fetchImpl?, maxPerCallUsd?, dailyLimitUsd?, maxPerHostUsd?, payNetworks?, 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); `payNetworks` (for example `["base"]`, the names `withNetworkPreference` takes) tells the caps which chains a pre-wrapped `fetch` without an `x402Client` pays on, so a call is counted at the dearest option on those chains (when none of a 402's options is on them, the dearest of all counts); `creditsKey` is a prepaid credits key (`a402_...`) used for paid tools when no `fetch` is given; `gateway` (`{ signer, networks? }`) pays the Circle Gateway batched accept where a 402 offers one, from the signer's Gateway deposit (see above); `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) |
@@ -365,8 +406,13 @@ caps hold at signing by default.
 `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
+option in an asset outside the table cannot be priced. With the `x402Client`
+passed, the signing guard drops such an option before anything is signed, so
+it is skipped beside an option that can be priced and the call pays that one;
+the call is refused only when no option can be priced. With a pre-wrapped
+`fetch` and no `x402Client`, nothing stops the wallet from signing it, so a
+capped call is refused before the wallet runs when any option in the `402`
+cannot be priced. 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:
@@ -398,7 +444,11 @@ const payFetch = wrapFetchWithPayment(fetch, client);
 Short names map to CAIP-2 (`base`, `solana`, `polygon`, `arbitrum`,
 `robinhood`); unknown entries pass through verbatim so future chains work
 without a package update. If the preference matches none of a seller's
-payment options it throws **before** any payment is signed.
+payment options it throws **before** any payment is signed. Since 0.8.19 a
+name resolves through the known-asset table (`NETWORK_NAMES`) to every id the
+chain is spelled with on the wire, and an id to the ids of its chain, so
+`["algorand"]`, or either spelling of Algorand mainnet, matches a seller that
+uses the other.
 
 
 ## Only pay who you meant to (`withPayeeAllowlist`)

package/index.js

@@ -19,8 +19,8 @@
 //   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 { quoteOf, guardSigning, networkIdsOf, acceptUsd } from "./known-assets.js";
+export { KNOWN_ASSETS, NETWORK_NAMES, knownAsset, acceptUsd, networkIdsOf } 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";
@@ -30,7 +30,7 @@ export { AsyncJobPendingError } from "./async-job.js";
 // `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.18";
+const VERSION = "0.8.20";
 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
@@ -67,6 +67,42 @@ async function shedRetryWaitMs(r, maxWaitMs = DISCOVERY_MAX_WAIT_MS) {
 
 const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// The Circle Gateway batched option: a second `exact` accept a seller may
+// offer on an EVM chain, named by `extra.name`, that a buyer pays from a USDC
+// balance deposited into Circle Gateway once (an on-chain transfer the buyer
+// pays gas for) by signing the same EIP-3009 TransferWithAuthorization under
+// the GatewayWalletBatched EIP-712 domain the accept carries (its name,
+// version and verifyingContract, with the chain's own id) instead of the
+// asset's. Gateway verifies and settles it off chain, so no gas rides on a
+// call. A stock x402 client signs under the asset's domain, so this is paid
+// here, by the signer the `gateway` option names, and only when that option
+// is set. A payment Gateway has not confirmed inside the seller's wait is
+// answered 402 with reason settlement-pending: the SAME header is resent
+// after the seller's Retry-After (never a new signature, which could be a
+// second charge), at most GATEWAY_PENDING_RESENDS times, each wait capped at
+// GATEWAY_PENDING_MAX_WAIT_MS; past that GatewayPendingError carries the
+// header to resend later.
+export const GATEWAY_KIND_NAME = "GatewayWalletBatched";
+const GATEWAY_TYPES = Object.freeze({
+  TransferWithAuthorization: [
+    { name: "from", type: "address" }, { name: "to", type: "address" }, { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" }, { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" },
+  ],
+});
+const GATEWAY_PENDING_RESENDS = 3;
+const GATEWAY_PENDING_MAX_WAIT_MS = 30_000;
+// The longest validity window a batched accept may ask for. A seller's
+// accept sets validBefore (now plus its maxTimeoutSeconds), and the signed
+// authorization is a bearer claim on the deposit until then, so an accept
+// asking for years is refused unsigned. Gateway's kinds publish a minimum
+// validity of seven days, and a seller derives its window from that plus a
+// small buffer, so seven days and an hour admits every honest accept.
+// Agent402's own accept adds VALIDITY_BUFFER_SECONDS (src/gateway-nanopayments.js)
+// to that minimum; scripts/test-gateway-nanopayments.js keeps it under this ceiling.
+export const GATEWAY_MAX_TIMEOUT_SECONDS = 7 * 24 * 3600 + 3600;
+const GATEWAY_DOCS_URL = "https://github.com/MikeyPetrillo/Agent402/wiki/Circle-Gateway";
+const EVM_ADDR = /^0x[0-9a-fA-F]{40}$/;
+
 // 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.
@@ -94,8 +130,14 @@ export class Agent402 {
    * @param {string[]} [opts.payNetworks]    the chains your pre-wrapped `fetch` pays on (e.g. ["base"], the
    *                                         names withNetworkPreference takes): without an x402Client the
    *                                         caps count the dearest accept on these chains, not on every chain
-   * @param {string} [opts.creditsKey]       a prepaid card-credits key (a402_...) - pays wallet-only tools on
+   * @param {string} [opts.creditsKey]       a prepaid credits key (a402_...) - pays wallet-only tools on
    *                                         Agent402's own services when no payFetch is given
+   * @param {{signer: {address: string, signTypedData: function}, networks?: string[]}} [opts.gateway]
+   *        Pay the Circle Gateway batched accept where a 402 offers one: `signer` is an
+   *        EIP-712 signer (a viem account: `address` and `signTypedData`) that holds a USDC
+   *        deposit in Circle Gateway; `networks` (chain names, as withNetworkPreference takes)
+   *        limits which chains' batched accepts it signs (default: any EVM chain offered). Off
+   *        by default. A 402 with no batched accept falls back to `fetch` or `creditsKey`.
    * @param {number|null} [opts.maxResponseBytes=33554432]
    *        Hard ceiling on a response body, enforced BEFORE it is parsed. null disables it.
    * @param {{id:string, validate:function}} [opts.outputValidator]
@@ -114,8 +156,9 @@ export class Agent402 {
   constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = undefined, tlsDistrust = true,
     maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null, x402Client = null, payNetworks = null,
     maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null,
-    respondAsync = "auto", asyncTimeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null } = {}) {
+    respondAsync = "auto", asyncTimeoutMs = DEFAULT_ASYNC_TIMEOUT_MS, onProgress = null, gateway = null } = {}) {
     this.respondAsync = respondAsync;
+    this.gateway = normalizeGateway(gateway);
     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;
@@ -160,7 +203,7 @@ export class Agent402 {
     if (x402Client) this.guardX402Client(x402Client);
     // The chains a pre-wrapped fetch pays on, as CAIP-2 ids (null = unknown).
     this._payNetworks = Array.isArray(payNetworks) && payNetworks.length
-      ? new Set(payNetworks.map((n) => String(NETWORK_CAIP2[String(n).trim().toLowerCase()] || String(n).trim()).toLowerCase()))
+      ? new Set(payNetworks.flatMap((n) => networkIdsOf(n)).map((id) => id.toLowerCase()))
       : null;
     // A response-size ceiling, enforced before parsing. See _readJson.
     this.maxResponseBytes = maxResponseBytes === null ? null : (numOrNull(maxResponseBytes) ?? DEFAULT_MAX_RESPONSE_BYTES);
@@ -500,6 +543,15 @@ export class Agent402 {
 
     // Wallet-only tool → settle in USDC via the provided x402 fetch.
     if (!tool.computePayable) {
+      // The Circle Gateway batched accept, when this client signs for it and
+      // the 402 offers one; otherwise the paths below, as without the option.
+      if (this.gateway) {
+        const paid = await this._gatewayCall(slug, tool, { paidSend, asyncHeaders, collect, cacheKey, cache, validator, maxResponseBytes });
+        if (paid !== NO_GATEWAY_ACCEPT) return paid;
+        if (!this.payFetch && !this.creditsKey) {
+          throw Object.assign(new Error(`call "${slug}" failed: HTTP 402 - the seller offers no Circle Gateway batched accept${this.gateway.networks ? ` on ${this.gateway.networks.join(", ")}` : ""} for this route, so the gateway signer cannot pay it; construct with { fetch: payFetch } to pay a plain accept`), { status: 402, slug, paid: false });
+        }
+      }
       if (this.payFetch) {
         // Spending policy: refuse to pay BEFORE signing if the price breaks a
         // configured ceiling (per-call / rolling-24h / per-host).
@@ -551,7 +603,7 @@ export class Agent402 {
         }
       }
       if (this.creditsKey) {
-        // Prepaid card credits: the server authorizes against the key's balance
+        // A prepaid credits key: the server authorizes against the key's balance
         // before the handler and debits only on a 200 (X-Credits-Balance tells
         // what is left). The same spend caps apply as on the wallet path, and
         // against the same number: a credits gate holds and debits the amount
@@ -612,6 +664,64 @@ export class Agent402 {
     return this._readJson(r, { maxBytes: maxResponseBytes, slug: "job", paid: true });
   }
 
+  /**
+   * Pay a wallet-only route on the Circle Gateway batched accept its 402
+   * offers. Reads the unpaid 402 (one round trip), picks the batched accept
+   * (gatewayAcceptOf), holds its amount to the caps BEFORE anything is
+   * signed, signs the authorization under the Gateway domain and sends it as
+   * the payment header on the plain fetch (never the payment-wrapped one,
+   * which would sign the plain accept). Returns NO_GATEWAY_ACCEPT, with
+   * nothing reserved or signed, when the answer is not a 402 or offers no
+   * batched accept this signer may pay, so the caller falls back. Once the
+   * signed header has been sent the amount is spent for the caps whatever
+   * comes back; only a signer that throws releases the reservation.
+   */
+  async _gatewayCall(slug, tool, { paidSend, asyncHeaders, collect, cacheKey, cache, validator, maxResponseBytes }) {
+    const pre = await paidSend();
+    if (pre?.status !== 402) return NO_GATEWAY_ACCEPT;
+    const env = await challengeEnvelope(pre);
+    const accept = gatewayAcceptOf(acceptsOf(env), this.gateway.networks);
+    if (!accept) return NO_GATEWAY_ACCEPT;
+    const host = hostOf(this.baseUrl);
+    const listUsd = parseUsd(tool.price);
+    // The amount the accept asks for, priced from the known-asset table
+    // (gatewayAcceptOf keeps only an accept that table can price); the
+    // catalog's figure never lowers what the caps are checked against.
+    const usd = Math.max(listUsd, acceptUsd(accept));
+    const reservation = this._spendReserve(host, usd, slug, listUsd);
+    let header;
+    try {
+      ({ header } = await signGatewayPayment(accept, { signer: this.gateway.signer, resource: env?.resource }));
+    } catch (e) {
+      // Nothing signed: the reservation is the only thing to undo.
+      this._spendRelease(reservation);
+      throw e;
+    }
+    // From here the signed authorization leaves this process. It is a bearer
+    // claim on the deposit until its validBefore whatever the seller answers
+    // (a refusal, a failure, a redirect, a job still running), so it counts
+    // as spent against the caps from the first send.
+    this._spendSettle(reservation);
+    const paidHeaders = { "PAYMENT-SIGNATURE": header, ...asyncHeaders };
+    let r = await collect(await paidSend(paidHeaders));
+    let body = null;
+    for (let resend = 0; ; resend++) {
+      if (r.status !== 402) break;
+      body = await readJsonQuietly(r);
+      const pending = body && typeof body === "object" && (body.reason === "settlement-pending" || body.retry === "same-payment");
+      if (!pending) break;
+      // Gateway may yet settle it: the header is handed back so the same
+      // payment can be resent later.
+      if (resend >= GATEWAY_PENDING_RESENDS) throw new GatewayPendingError(slug, header, body);
+      const retryAfterSec = Number(r.headers?.get?.("retry-after")) || Number(body.retryAfterSeconds) || 10;
+      await this._sleep(Math.min(Math.max(0, retryAfterSec) * 1000, GATEWAY_PENDING_MAX_WAIT_MS));
+      r = await collect(await paidSend(paidHeaders));
+    }
+    if (r.status === 402) throw this._fail(slug, r, gatewayRefusalMessage(slug, body, accept, this.gateway.signer.address));
+    if (!r.ok) throw this._fail(slug, r, await this._failureDetail(slug, r));
+    return this._deliverResponse(slug, r, cacheKey, cache, validator, { maxResponseBytes, paid: true });
+  }
+
   async _assertOutput(slug, body, validator, { paid = false, cacheHit = false } = {}) {
     if (!validator) return body;
     try {
@@ -656,8 +766,9 @@ export class Agent402 {
    *  "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, among the chains in `payNetworks` when they are given, and one
-   *  that cannot be priced is refused here), or "credits" (nothing is signed:
+   *  one counts, among the chains in `payNetworks` when they are given, and an
+   *  accept this client cannot price is refused here, since nothing stops the
+   *  wallet from signing it), or "credits" (nothing is signed:
    *  the credits gate debits the route's own quote, and no accept is below it,
    *  since a chain premium or price floor only raises an accept, so the
    *  cheapest known accept counts).
@@ -682,11 +793,19 @@ export class Agent402 {
       return listUsd; /* no readable 402: the advertised price */
     }
     if (!q) return listUsd;
-    if (q.max == null || (mode === "wallet" && q.unknown > 0)) {
+    // An option in an asset this client cannot price: with no guard the wallet
+    // may sign it, for an amount no cap was checked against, so one such
+    // option refuses the call; the guard drops it before signing, so beside a
+    // priced option it is skipped there; a credits gate signs nothing, so it
+    // is ignored. An offer with nothing priceable is refused under a cap in
+    // either signing mode.
+    const unpriceable = q.max == null || (mode === "wallet" && q.unknown > 0);
+    if (unpriceable) {
       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 });
+      throw new SpendingLimitError(q.max == null
+        ? `refusing to pay for "${slug}" - no payment option it offers is in an asset this client can 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)" : ""}`
+        : `refusing to pay for "${slug}" - ${q.unknown} of its ${q.total} payment options ${q.unknown === 1 ? "is" : "are"} in an asset this client cannot price, and without the signing guard the wallet may sign any of them (pass your x402Client to guard signing and pay the options it can price)`,
+      { limit: "knownAsset", slug, priceUsd: null, unknownOptions: q.unknown });
     }
     const quoted = mode === "wallet" ? q.max : q.min;
     // Larger of the two: an understated catalog must not lower the ceiling
@@ -850,6 +969,105 @@ export class SpendingLimitError extends Error {
   }
 }
 
+/** A Circle Gateway batched payment the seller had not confirmed after the
+ *  resends. `paymentHeader` is the signed payment: resend the same request
+ *  with it as PAYMENT-SIGNATURE to be served once Gateway confirms it, with
+ *  no new charge. Never sign a new authorization for the same request. The
+ *  amount counts against the caps (Gateway may settle it). */
+export class GatewayPendingError extends Error {
+  constructor(slug, paymentHeader, body = null) {
+    super(`"${slug}" is paid on the Circle Gateway batched option and Gateway had not confirmed the payment after ${GATEWAY_PENDING_RESENDS} resends; resend the same request with the same PAYMENT-SIGNATURE header (paymentHeader) after a short wait, never a new signature${body?.hint ? ` - ${body.hint}` : ""}`);
+    this.name = "GatewayPendingError";
+    this.slug = slug;
+    this.paymentHeader = paymentHeader;
+    this.status = 402;
+    this.paid = null;
+    this.retryAfterSeconds = Number(body?.retryAfterSeconds) || null;
+  }
+}
+
+/** Sentinel: the 402 offered no batched accept this client signs for. */
+const NO_GATEWAY_ACCEPT = Symbol("no-gateway-accept");
+
+async function readJsonQuietly(r) {
+  try { return await (typeof r?.clone === "function" ? r.clone() : r).json(); } catch { return null; }
+}
+
+function normalizeGateway(value) {
+  if (value == null || value === false) return null;
+  if (typeof value !== "object") throw new TypeError("gateway must be { signer, networks? }");
+  const signer = value.signer;
+  if (!signer || typeof signer.signTypedData !== "function" || !EVM_ADDR.test(String(signer.address || ""))) {
+    throw new TypeError("gateway.signer must be an EIP-712 signer with an EVM address and signTypedData (a viem account)");
+  }
+  const networks = Array.isArray(value.networks) && value.networks.length ? value.networks.map(String) : null;
+  return Object.freeze({ signer, networks });
+}
+
+/** The first Circle Gateway batched accept a buyer may pay: scheme exact,
+ *  `extra.name` the Gateway kind, on an EVM chain (among `networks` when
+ *  given), with a payTo, a verifyingContract, a domain version, a validity
+ *  window of at most GATEWAY_MAX_TIMEOUT_SECONDS and an amount in a known
+ *  asset (so the caps can price it; a batched accept in an asset the table
+ *  does not know is never signed). null when there is none. */
+export function gatewayAcceptOf(accepts, networks = null) {
+  const list = Array.isArray(accepts) ? accepts : [];
+  const wanted = networks ? new Set(networks.flatMap((n) => networkIdsOf(n)).map((id) => id.toLowerCase())) : null;
+  return list.find((a) => a && typeof a === "object" && a.scheme === "exact"
+    && a.extra && typeof a.extra === "object" && a.extra.name === GATEWAY_KIND_NAME
+    && /^eip155:[0-9]{1,12}$/.test(String(a.network || "")) && (!wanted || wanted.has(String(a.network).toLowerCase()))
+    && EVM_ADDR.test(String(a.payTo || "")) && EVM_ADDR.test(String(a.extra.verifyingContract || ""))
+    && typeof a.extra.version === "string" && /^[0-9]{1,4}$/.test(a.extra.version)
+    && /^[0-9]{1,78}$/.test(String(a.amount ?? "")) && Number(a.maxTimeoutSeconds) > 0 && Number(a.maxTimeoutSeconds) <= GATEWAY_MAX_TIMEOUT_SECONDS
+    && acceptUsd(a) != null) || null;
+}
+
+/**
+ * Sign a Circle Gateway batched payment for one accept: an EIP-3009
+ * TransferWithAuthorization from the signer to the accept's payTo for exactly
+ * its amount, valid from now (validAfter 0) for the accept's
+ * maxTimeoutSeconds, under the Gateway EIP-712 domain the accept carries
+ * (name, version, verifyingContract) with the accept's chain id. Returns the
+ * x402 v2 payment payload and its base64 header value.
+ */
+export async function signGatewayPayment(accept, { signer, resource = undefined, now = Date.now, nonce = undefined } = {}) {
+  if (!signer || typeof signer.signTypedData !== "function" || !EVM_ADDR.test(String(signer.address || ""))) throw new TypeError("signGatewayPayment needs a signer with an EVM address and signTypedData");
+  if (!gatewayAcceptOf([accept])) throw new TypeError("signGatewayPayment needs a Circle Gateway batched accept (scheme exact, extra.name GatewayWalletBatched, an EVM network, payTo, verifyingContract, version, amount, maxTimeoutSeconds)");
+  const nowSec = Math.floor(now() / 1000);
+  const authorization = {
+    from: signer.address, to: accept.payTo, value: String(accept.amount),
+    validAfter: "0", validBefore: String(nowSec + Math.floor(Number(accept.maxTimeoutSeconds))),
+    nonce: nonce || `0x${randomBytes(32).toString("hex")}`,
+  };
+  const signature = await signer.signTypedData({
+    domain: { name: accept.extra.name, version: accept.extra.version, chainId: Number(String(accept.network).split(":")[1]), verifyingContract: accept.extra.verifyingContract },
+    types: GATEWAY_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: { ...authorization, value: BigInt(authorization.value), validAfter: BigInt(authorization.validAfter), validBefore: BigInt(authorization.validBefore) },
+  });
+  const payload = { x402Version: 2, ...(resource && typeof resource === "object" ? { resource } : {}), accepted: accept, payload: { signature, authorization } };
+  return { payload, header: Buffer.from(JSON.stringify(payload)).toString("base64") };
+}
+
+/** The message for a 402 that refused a batched payment: the seller's own
+ *  explanation first, and when it says the Gateway balance came up short,
+ *  what to do about it (deposit, never a resend of the same authorization).
+ *  A short balance is read from the machine fields the seller sends (reason
+ *  insufficient-funds, or retry fund-gateway-deposit); the prose is read only
+ *  when a body carries neither field. */
+function gatewayRefusalMessage(slug, body, accept, address) {
+  const said = body && typeof body === "object" ? (body.hint ?? body.detail ?? body.error ?? body.message) : null;
+  const reason = typeof body?.reason === "string" ? body.reason : null;
+  const retry = typeof body?.retry === "string" ? body.retry : null;
+  const short = reason != null || retry != null
+    ? reason === "insufficient-funds" || retry === "fund-gateway-deposit"
+    : /insufficient|balance|underflow|not enough/i.test(typeof said === "string" ? said : "");
+  const chain = String(accept.network);
+  return `call "${slug}" refused on the Circle Gateway batched option (${chain}): HTTP 402${said != null ? ` - ${typeof said === "string" ? said : JSON.stringify(said)}` : ""}${short
+    ? ` The signer ${address} needs a USDC balance in Circle Gateway on that chain: deposit through Circle's GatewayWallet contract first (this client never deposits), then call again; see ${GATEWAY_DOCS_URL}.`
+    : ""} The refused authorization was sent and stays valid until its validBefore, so it counts against this client's spending caps.`;
+}
+
 /** 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
@@ -869,16 +1087,22 @@ export async function quoted402Usd(res) {
 
 /** The accepts array of a 402, from the PAYMENT-REQUIRED header first, then the body. */
 async function challengeAccepts(res) {
+  return acceptsOf(await challengeEnvelope(res));
+}
+
+/** The decoded PaymentRequired object of a 402 (the header first, then the
+ *  body), or null when neither carries accepts. */
+async function challengeEnvelope(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 acceptsOf(body);
+  return acceptsOf(body) ? body : null;
 }
 
 function decodeChallengeHeader(header) {
   if (typeof header !== "string" || !header.trim()) return null;
-  try { return acceptsOf(JSON.parse(Buffer.from(header.trim(), "base64").toString("utf8"))); } catch { return null; }
+  try { const obj = JSON.parse(Buffer.from(header.trim(), "base64").toString("utf8")); return acceptsOf(obj) ? obj : null; } catch { return null; }
 }
 
 /** The accepts array, at the top level or under the envelope keys sellers wrap it in. */
@@ -961,9 +1185,12 @@ function resultCacheKey(slug, params, validator) {
  *   withNetworkPreference(x402client, ["robinhood"]);       // or ["eip155:4663"]
  *   const payFetch = wrapFetchWithPayment(fetch, x402client);
  *
- * Short names map to CAIP-2; unknown entries pass through verbatim so future
- * chains work without a package update. Throws (before paying) when the
- * preference matches none of a seller's payment options.
+ * A name resolves through the known-asset table to every id that chain is
+ * spelled with on the wire (./known-assets.js NETWORK_NAMES), and an id to
+ * the ids of its chain, so either spelling of a chain matches the other;
+ * unknown entries pass through verbatim so future chains work without a
+ * package update. Throws (before paying) when the preference matches none of
+ * a seller's payment options.
  */
 export const NETWORK_CAIP2 = {
   base: "eip155:8453",
@@ -980,16 +1207,17 @@ export const NETWORK_CAIP2 = {
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
   stellar: "stellar:pubnet",
-  algorand: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+  algorand: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
 };
 
 export function withNetworkPreference(client, networks) {
-  const prefs = (networks || []).map((n) => NETWORK_CAIP2[String(n).trim().toLowerCase()] || String(n).trim());
+  // Every id each preference names, in preference order, once each.
+  const prefs = [...new Set((networks || []).flatMap((n) => networkIdsOf(n)))];
   if (!prefs.length) return client;
   const orig = client.createPaymentPayload.bind(client);
   client.createPaymentPayload = (paymentRequired) => {
     const list = Array.isArray(paymentRequired?.accepts) ? paymentRequired.accepts : [];
-    const picked = prefs.flatMap((caip2) => list.filter((a) => String(a?.network || "").toLowerCase() === caip2.toLowerCase()));
+    const picked = prefs.flatMap((id) => list.filter((a) => String(a?.network || "").toLowerCase() === id.toLowerCase()));
     if (!picked.length) {
       const offered = [...new Set(list.map((a) => a?.network).filter(Boolean))];
       throw new Error(`network preference [${prefs.join(", ")}] matched none of the seller's payment options [${offered.join(", ")}]`);

package/known-assets.js

@@ -32,10 +32,46 @@ export const KNOWN_ASSETS = Object.freeze({
   "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: USDC is ASA 31566704. Mainnet is named by its CAIP-2 id (the
+  // first 32 characters of the base64 genesis hash) and, by sellers that
+  // predate it, by the full hash.
+  "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k": [{ asset: "31566704", decimals: 6, symbol: "USDC" }],
   "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=": [{ asset: "31566704", decimals: 6, symbol: "USDC" }],
 });
 
+/** Chain name -> every network id in the table that names that chain. A
+ *  chain spelled two ways on the wire lists both, so a buyer's preference by
+ *  name, or by either spelling, matches a seller's accept in the other. */
+export const NETWORK_NAMES = Object.freeze({
+  base: ["eip155:8453"],
+  "base-sepolia": ["eip155:84532"],
+  polygon: ["eip155:137"],
+  arbitrum: ["eip155:42161"],
+  monad: ["eip155:143"],
+  celo: ["eip155:42220"],
+  avalanche: ["eip155:43114"],
+  sei: ["eip155:1329"],
+  optimism: ["eip155:10"],
+  arc: ["eip155:5042"],
+  robinhood: ["eip155:4663"],
+  solana: ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+  "solana-devnet": ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],
+  stellar: ["stellar:pubnet"],
+  algorand: ["algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k", "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="],
+});
+
+/** The network ids a preference names: a chain name's ids; for an id, every
+ *  id of the chain it belongs to (so either spelling matches the other); an
+ *  id the table does not know passes through as itself. */
+export function networkIdsOf(pref) {
+  const p = String(pref || "").trim();
+  if (!p) return [];
+  const byName = NETWORK_NAMES[p.toLowerCase()];
+  if (byName) return [...byName];
+  for (const ids of Object.values(NETWORK_NAMES)) if (ids.some((id) => id.toLowerCase() === p.toLowerCase())) return [...ids];
+  return [p];
+}
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.18",
+  "version": "0.8.20",
   "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",