agent402-client 0.8.16 → 0.8.18

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)
 
@@ -215,7 +228,7 @@ that runs as one.
 
 | Method | What |
 |---|---|
-| `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) |
+| `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) |
 | `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) |
@@ -361,7 +374,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`)

package/index.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.16";
+const VERSION = "0.8.18";
 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
@@ -91,8 +91,11 @@ export class Agent402 {
    * @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 {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
+   *                                         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]
@@ -109,7 +112,7 @@ export class Agent402 {
    *        ({ 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, x402Client = null,
+    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 } = {}) {
     this.respondAsync = respondAsync;
@@ -155,6 +158,10 @@ export class Agent402 {
     this._signCtx = new AsyncLocalStorage();
     this._guarded = false;
     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()))
+      : null;
     // 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
@@ -574,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,
@@ -649,8 +656,11 @@ 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, and one that cannot be priced is refused here), or "credits"
-   *  (nothing is signed; the dearest known accept counts).
+   *  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:
+   *  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).
    *  @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;
@@ -658,7 +668,14 @@ export class Agent402 {
     try {
       const pre = await send();
       if (pre?.status !== 402) return listUsd;
-      q = quoteOf(await challengeAccepts(pre));
+      let accepts = await challengeAccepts(pre);
+      if (mode === "wallet" && this._payNetworks && Array.isArray(accepts)) {
+        const onChains = accepts.filter((a) => this._payNetworks.has(String(a?.network || "").toLowerCase()));
+        // No option on the declared chains (or a name that maps to none): the
+        // wallet may still sign any of them, so the dearest of all counts.
+        if (onChains.length) accepts = onChains;
+      }
+      q = quoteOf(accepts);
     } catch (e) {
       // A redirect is refused here, before anything is reserved or signed.
       if (e instanceof PaymentRedirectError) throw e;
@@ -671,7 +688,7 @@ export class Agent402 {
         `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;
+    const quoted = mode === "wallet" ? q.max : q.min;
     // Larger of the two: an understated catalog must not lower the ceiling
     // the cap is checked against.
     return Math.max(listUsd, quoted);
@@ -955,8 +972,15 @@ export const NETWORK_CAIP2 = {
   "base-sepolia": "eip155:84532",
   robinhood: "eip155:4663",
   arc: "eip155:5042",
+  monad: "eip155:143",
+  celo: "eip155:42220",
+  avalanche: "eip155:43114",
+  sei: "eip155:1329",
+  optimism: "eip155:10",
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+  stellar: "stellar:pubnet",
+  algorand: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
 };
 
 export function withNetworkPreference(client, networks) {

package/package.json

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