agent402-client 0.3.0 → 0.4.1

package/README.md

@@ -67,7 +67,7 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 
 Want to see who's actually getting paid on x402 right now — not just what tools
 this service exposes? `topSellers()` returns the live leaderboard of sellers
-settling USDC on Base in the last ~24h, derived from on-chain transfers. Free
+settling USDC (primarily on Base) in the last ~24h, derived from on-chain transfers. Free
 to call (no payment, no proof-of-work):
 
 ```js
@@ -86,7 +86,7 @@ await a.topSellers({ sort: "calls", include: "all" });
 | `await a.find(task, { k = 5 })` | Resolve a plain-language task to the best-matching tools (route, price, schema, example) |
 | `await a.findWorkflows(task, { k = 2 })` | Resolve a task to matching multi-tool workflow templates (skill packs) |
 | `await a.getWorkflowPrompt(slug, args)` | Fetch the rendered prompt messages for a skill pack with arguments substituted in |
-| `await a.topSellers({ limit?, sort?, include? })` | Live x402 leaderboard: which sellers are settling the most USDC on Base in the last ~24h (free, no payment) |
+| `await a.topSellers({ limit?, sort?, include? })` | Live x402 leaderboard: which sellers are settling the most USDC (primarily on Base) in the last ~24h (free, no payment) |
 | `await a.call(slug, params, { idempotencyKey?, cache? })` | Call a tool; auto-pays (PoW for free tools, x402 for wallet-only); returns the JSON result |
 | `Agent402.solvePow(pow)` | Solve a proof-of-work challenge object → an `X-Pow-Solution` value |
 | `a.clearCache()` | Drop the in-memory result cache |
@@ -94,3 +94,26 @@ await a.topSellers({ sort: "calls", include: "all" });
 - **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.
 - MIT licensed. Part of [Agent402](https://github.com/MikeyPetrillo/Agent402).
+
+## Pick the settlement chain (`withNetworkPreference`)
+
+Multi-chain sellers list Base first, so an unmodified x402 client effectively
+always settles there. To pin a chain — e.g. **USDG on Robinhood Chain** —
+wrap your client before building the fetch:
+
+```js
+import { withNetworkPreference } from "agent402-client";
+import { x402Client } from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+
+const client = new x402Client();
+registerExactEvmScheme(client, { signer });
+withNetworkPreference(client, ["robinhood"]);   // or ["base","solana"], or ["eip155:4663"]
+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.

package/index.js

@@ -110,6 +110,26 @@ export class Agent402 {
     };
   }
 
+  /**
+   * Register a wallet address for Base builder code attribution. Idempotent:
+   * the same wallet always returns the same code. No authentication required.
+   *
+   * @param {string} walletAddress  the caller's wallet address (e.g. "0x…")
+   * @param {object} [opts]
+   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
+   * @returns {Promise<{builderCode:string, walletAddress:string}>}
+   */
+  static async registerBuilderCode(walletAddress, { fetchImpl = globalThis.fetch } = {}) {
+    if (!walletAddress || typeof walletAddress !== "string") throw new Error("walletAddress is required");
+    const r = await fetchImpl("https://api.base.dev/v1/agents/builder-codes", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ walletAddress }),
+    });
+    if (!r.ok) throw new Error(`builder code registration failed: HTTP ${r.status}`);
+    return r.json();
+  }
+
   /** Solve a proof-of-work challenge object (from a 402 body) into an X-Pow-Solution value. */
   static solvePow(pow) {
     let n = 0;
@@ -178,4 +198,45 @@ export class Agent402 {
   clearCache() { this._cache?.clear(); }
 }
 
+/**
+ * Restrict + order which chains an @x402 client will pay on (duck-typed — any
+ * client version with createPaymentPayload works, zero new dependencies).
+ * Multi-chain sellers list Base first, so an unmodified client effectively
+ * always settles there; this makes rails like USDG on Robinhood Chain
+ * (eip155:4663) reachable:
+ *
+ *   import { withNetworkPreference } from "agent402-client";
+ *   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.
+ */
+export const NETWORK_CAIP2 = {
+  base: "eip155:8453",
+  polygon: "eip155:137",
+  arbitrum: "eip155:42161",
+  "base-sepolia": "eip155:84532",
+  robinhood: "eip155:4663",
+  solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+};
+
+export function withNetworkPreference(client, networks) {
+  const prefs = (networks || []).map((n) => NETWORK_CAIP2[String(n).trim().toLowerCase()] || String(n).trim());
+  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()));
+    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(", ")}]`);
+    }
+    return orig({ ...paymentRequired, accepts: picked });
+  };
+  return client;
+}
+
 export default Agent402;

package/package.json

@@ -1,19 +1,48 @@
 {
   "name": "agent402-client",
-  "version": "0.3.0",
-  "description": "Tiny buyer-side client for Agent402 (x402): resolve a task to a tool 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. Caching + idempotent retries.",
+  "version": "0.4.1",
+  "description": "Buyer-side SDK for Agent402.Tools (x402): resolve a task to a tool across 1,346 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 or USDG on Robinhood Chain). Caching, idempotent retries, cross-seller Smart Order Router.",
   "type": "module",
   "main": "index.js",
-  "exports": { ".": "./index.js" },
-  "files": ["index.js", "README.md"],
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node test.js" },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
   "keywords": [
-    "x402", "ai-agents", "agent-tools", "llm-tools", "usdc", "base",
-    "proof-of-work", "http-402", "micropayments", "mcp", "client", "sdk"
+    "x402",
+    "ai-agents",
+    "agent-tools",
+    "llm-tools",
+    "usdc",
+    "base",
+    "proof-of-work",
+    "http-402",
+    "micropayments",
+    "mcp",
+    "client",
+    "sdk",
+    "agent402",
+    "tool-discovery",
+    "smart-order-router",
+    "robinhood-chain",
+    "usdg",
+    "multi-chain"
   ],
-  "author": "Mikey Petrillo (https://github.com/MikeyPetrillo)",
+  "author": "Mike Petrillo <mike@agent402.tools> (https://github.com/MikeyPetrillo)",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/MikeyPetrillo/Agent402.git", "directory": "client" },
-  "homepage": "https://github.com/MikeyPetrillo/Agent402/tree/main/client"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MikeyPetrillo/Agent402.git",
+    "directory": "client"
+  },
+  "homepage": "https://agent402.tools"
 }