agent402-client 0.8.17 → 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)
 
@@ -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.17";
+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
@@ -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]
@@ -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,

package/package.json

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