agent402-client 0.8.17 → 0.8.19

package/README.md

@@ -5,7 +5,7 @@ instance) - the buy side of [Agentic Finance](https://agent402.tools/agentic-fin
 agents paying per request over x402 or MPP. **Resolve a task to a tool, then call it - with payment handled for
 you.** Free pure-CPU tools settle with a built-in proof-of-work (no wallet, zero
 dependencies); wallet-only tools settle via an x402- or MPP-wrapped fetch you
-provide, or through a prepaid credits key already issued. Results are cached, and every
+provide, or through a prepaid credits key. Results are cached, and every
 send carries an `Idempotency-Key` that is stable per client and per operation, so
 a retried lost response replays the paid answer on the credits and proof-of-work
 paths (the wallet path is different: see "Retries and double charges").
@@ -71,11 +71,14 @@ const a = new Agent402({ fetch: payFetch });
 const article = await a.call("extract", { url: "https://agent402.tools/guides/x402-in-5-minutes" });
 ```
 
-## Prepaid credits (keys already issued)
+## Paying with a credits key
 
-New credits are not on sale. A key already issued (`a402_...`) still works: pass it
+A prepaid credits key (`a402_...`; agent402.tools/credits says whether packs are on
+sale) pays for Agent402's own services: pass it
 as `creditsKey` and the SDK sends `Authorization: Bearer a402_...` on wallet-only
-calls (the wallet-scoped routes, memory and usage, refuse it and need a wallet); the server authorizes
+calls (the wallet-scoped routes, memory and usage, refuse it and need a wallet, as do
+the routes that buy from an outside seller: the route-execute tiers,
+`seller-payability`, `decide-execute` and the flight routes); the server authorizes
 against the key's balance before the handler runs and debits the list price only
 on a successful (200) response (the `X-Credits-Balance` header carries what is
 left; credits never expire). A refused call throws with the balance; nothing is
@@ -116,7 +119,17 @@ What the server does with it depends on how the call was paid:
   dedupe). So on the wallet path a retry after a lost response can settle twice;
   the `Idempotency-Key` cannot prevent that on its own. If that matters for your
   workload, use a credits key for the tools you retry, or keep the signed
-  request and resend it yourself.
+  request and resend it yourself. A resent signed request needs no key: the
+  server answers a request re-sent with the same signed EVM payment, to the same
+  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.
 
 ## Workflows (skill packs)
 
@@ -352,8 +365,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:
@@ -361,7 +379,7 @@ 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.
+- **Non-custodial:** paid settlement is your `@x402/fetch` / `mppx` fetch + wallet (or a prepaid credits key); this client never sees a private key.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).
 
 ## Pick the settlement chain (`withNetworkPreference`)
@@ -385,7 +403,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 } 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.17";
+const VERSION = "0.8.19";
 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
@@ -94,8 +94,8 @@ 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_...) already issued (new credits are
-   *                                         not on sale) - pays wallet-only tools when no payFetch is given
+   * @param {string} [opts.creditsKey]       a prepaid card-credits key (a402_...) - pays wallet-only tools on
+   *                                         Agent402's own services when no payFetch is given
    * @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]
@@ -160,7 +160,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);
@@ -581,7 +581,7 @@ export class Agent402 {
       }
       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 });
-      throw this._fail(slug, r, `call "${slug}" failed: HTTP ${r.status} - wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch) or { creditsKey } (a prepaid credits key already issued; new credits are not on sale)`);
+      throw this._fail(slug, r, `call "${slug}" failed: HTTP ${r.status} - wallet-only tool; construct with { fetch: payFetch } (an @x402/fetch-wrapped fetch) or { creditsKey } (a prepaid credits key; routes that buy from an outside seller need a wallet)`);
     }
 
     // Free (compute-payable) tool: succeeds plainly on a FREE_MODE instance,
@@ -656,8 +656,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 +683,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
@@ -961,9 +970,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 +992,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.17",
+  "version": "0.8.19",
   "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",