agent402-client 0.5.1 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Havok Holdings LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,6 +11,8 @@ never double-charges.
 npm install agent402-client
 ```
 
+Runnable copy of the free-tier quickstart below: [`examples/hello-agent402.js`](https://github.com/MikeyPetrillo/Agent402/blob/main/examples/hello-agent402.js) — discover a tool and call it in ~15 lines, no wallet.
+
 ## Free tier (proof-of-work, no wallet)
 
 ```js
@@ -117,9 +119,18 @@ try {
 
 Only **settled** paid calls count against the rolling window — a blocked or failed
 call never consumes budget. Free proof-of-work calls are never counted. Omit a cap
-(or leave it `null`) for no limit; with none set, behavior is unchanged. This is a
-buyer-side circuit breaker against a malicious or misconfigured `402` that quotes an
-inflated price.
+(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.)
 
 - **Zero dependencies** for the free/proof-of-work path (uses `node:crypto`).
 - **Non-custodial:** paid settlement is your `@x402/fetch` + wallet; this client never sees your key.

package/index.js

@@ -14,6 +14,13 @@
 //   const a = new Agent402({ fetch: payFetch });
 import { createHash } from "node:crypto";
 
+// 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.6.1";
+const USER_AGENT = `agent402-client/${VERSION}`;
+
 const leadingZeroBits = (buf) => { let n = 0; for (const b of buf) { if (b === 0) { n += 8; continue; } n += Math.clz32(b) - 24; break; } return n; };
 
 export class Agent402 {
@@ -32,7 +39,9 @@ export class Agent402 {
     if (typeof fetchImpl !== "function") throw new Error("No fetch available — pass { fetchImpl } on Node < 18");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
-    this.f = fetchImpl;
+    // Wrap the plain fetch so every request identifies the SDK (see USER_AGENT
+    // above). Caller-supplied init.headers still win on a key collision.
+    this.f = (url, init = {}) => fetchImpl(url, { ...init, headers: { "User-Agent": USER_AGENT, ...(init.headers || {}) } });
     this._catalog = null;
     this._cache = cache ? new Map() : null;
     // Spending policy (defends the x402 "wallet drain via uncapped spending"
@@ -167,7 +176,9 @@ export class Agent402 {
 
     const idem = idempotencyKey || `a402-${createHash("sha256").update(`${cacheKey}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`;
     const send = (extraHeaders = {}, useFetch = this.f) => {
-      const headers = { "Idempotency-Key": idem, ...extraHeaders };
+      // 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 };
       if (tool.method === "GET") {
@@ -183,15 +194,38 @@ export class Agent402 {
     // Wallet-only tool → settle in USDC via the provided x402 fetch.
     if (!tool.computePayable) {
       if (this.payFetch) {
-        // Spending policy: refuse to pay BEFORE signing if the quoted price
-        // breaks a configured ceiling (per-call / rolling-24h / per-host).
-        const usd = parseUsd(tool.price);
+        // Spending policy: refuse to pay BEFORE signing if the price breaks a
+        // configured ceiling (per-call / rolling-24h / per-host).
         const host = hostOf(this.baseUrl);
-        this._spendCheck(host, usd, slug);
-        const r = await send({}, this.payFetch);
-        if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
-        this._spendCommit(host, usd); // record spend only once the call actually settled
-        return this._store(cacheKey, await r.json(), cache);
+        let usd = parseUsd(tool.price);
+        // The catalog price is seller-ADVERTISED — a hostile server could under-
+        // state it and then quote more in the 402. When a cap is set, preflight
+        // the 402 to learn the price the wallet will actually be asked to sign and
+        // check the cap against the larger of the two. Fail-open: if the 402 can't
+        // be read (FREE_MODE / non-402 / unparseable), fall back to the advertised
+        // price — never block a legitimate payment on a parse miss.
+        if (this._spendCapsConfigured()) {
+          try {
+            const pre = await send();
+            if (pre.status === 402) {
+              const quoted = parse402Usd(await pre.json().catch(() => null));
+              if (quoted != null) usd = Math.max(usd, quoted);
+            }
+          } catch { /* fail-open to the advertised price */ }
+        }
+        // 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);
+        try {
+          const r = await send({}, this.payFetch);
+          if (!r.ok) throw new Error(`call "${slug}" failed: HTTP ${r.status}`);
+          this._spendSettle(reservation); // confirm the reservation as settled spend
+          return this._store(cacheKey, await r.json(), cache);
+        } catch (e) {
+          this._spendRelease(reservation); // roll back — nothing settled
+          throw e;
+        }
       }
       const r = await send(); // no wallet — succeeds only on a FREE_MODE instance
       if (r.ok) return this._store(cacheKey, await r.json(), cache);
@@ -249,13 +283,36 @@ export class Agent402 {
     }
   }
 
-  /** Record a settled paid call against the rolling budget. */
-  _spendCommit(host, usd) { if (usd > 0) this._spend.log.push({ ts: Date.now(), host, usd }); }
+  /** True if any spending ceiling is configured (worth preflighting the 402). */
+  _spendCapsConfigured() {
+    const s = this._spend;
+    return s.maxPerCall != null || s.daily != null || s.perHost != null;
+  }
+
+  /** Check caps AND reserve the amount atomically (no await in between), so
+   *  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) {
+    this._spendCheck(host, usd, slug);
+    if (!(usd > 0)) return null;
+    const entry = { ts: Date.now(), host, usd, pending: true };
+    this._spend.log.push(entry);
+    return entry;
+  }
+  /** Confirm a reservation as settled spend. */
+  _spendSettle(entry) { if (entry) entry.pending = false; }
+  /** Roll back a reservation whose call did not settle (failed / errored). */
+  _spendRelease(entry) {
+    if (!entry) return;
+    const i = this._spend.log.indexOf(entry);
+    if (i >= 0) this._spend.log.splice(i, 1);
+  }
 
   /** Rolling-24h spend summary (settled paid calls only) — for observability. */
   spendingSummary() {
     const cutoff = Date.now() - 24 * 60 * 60 * 1000;
-    const log = this._spend.log.filter((e) => e.ts >= cutoff);
+    const log = this._spend.log.filter((e) => e.ts >= cutoff && !e.pending);
     const byHost = {};
     for (const e of log) byHost[e.host] = Number(((byHost[e.host] || 0) + e.usd).toFixed(6));
     return {
@@ -277,6 +334,25 @@ 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.
+function parse402Usd(body) {
+  const accepts = body && body.accepts;
+  if (!Array.isArray(accepts) || !accepts.length) return null;
+  let maxUsd = 0;
+  for (const a of accepts) {
+    const atomic = Number(a && a.maxAmountRequired);
+    if (!Number.isFinite(atomic) || atomic < 0) return null;
+    const decimals = Number((a && a.extra && a.extra.decimals) ?? (a && a.decimals) ?? 6);
+    if (!Number.isFinite(decimals) || decimals < 0 || decimals > 30) return null;
+    const usd = atomic / 10 ** decimals;
+    if (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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent402-client",
-  "version": "0.5.1",
-  "description": "Buyer-side SDK for Agent402.Tools (x402): resolve a task to a tool across 1,407 pay-per-call endpoints and call it with payment handled for you — free tools settle via built-in proof-of-work (no wallet), wallet-only tools via your x402 fetch — with a withNetworkPreference helper to pick the settlement chain (USDC on Base/Solana/Polygon/Arbitrum/Stellar or USDG on Robinhood Chain). Caching, idempotent retries, cross-seller Smart Order Router.",
+  "version": "0.6.1",
+  "description": "Buyer-side SDK for Agent402.Tools (x402): resolve a task to a tool across a catalog of 500 pay-per-call endpoints (400 tools + 100 skill packs) and call it with payment handled for you — free tools settle via built-in proof-of-work (no wallet), wallet-only tools via your x402 fetch — with a withNetworkPreference helper to pick the settlement chain (USDC on Base/Solana/Polygon/Arbitrum/Monad/Stellar/Algorand or USDG on Robinhood Chain — 8 chains). Caching, idempotent retries, cross-seller Smart Order Router.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -27,7 +27,9 @@
     "solana",
     "polygon",
     "arbitrum",
+    "monad",
     "stellar",
+    "algorand",
     "proof-of-work",
     "http-402",
     "micropayments",
@@ -41,7 +43,7 @@
     "usdg",
     "multi-chain"
   ],
-  "author": "Mike Petrillo <mike@agent402.tools> (https://github.com/MikeyPetrillo)",
+  "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "license": "MIT",
   "repository": {
     "type": "git",