agent402-client 0.2.1 → 0.4.0

package/README.md

@@ -63,6 +63,21 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 // → feed messages straight to any LLM
 ```
 
+## Discover the live x402 economy
+
+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 (primarily on Base) in the last ~24h, derived from on-chain transfers. Free
+to call (no payment, no proof-of-work):
+
+```js
+const { window, asOf, results, totalSellers } = await a.topSellers({ limit: 10 });
+// → { window: "24h", asOf, totalSellers, results: [{ rank, name, wallet, totalUsd, callsSettled, uniqueBuyers, ... }] }
+
+// Rank by call volume instead of USDC, and include the host's own wallet:
+await a.topSellers({ sort: "calls", include: "all" });
+```
+
 ## API
 
 | Method | What |
@@ -71,6 +86,7 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 | `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 (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 |
@@ -78,3 +94,26 @@ const { messages } = await a.getWorkflowPrompt("security-audit", { domain: "stri
 - **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

@@ -77,6 +77,59 @@ export class Agent402 {
     return r.json();
   }
 
+  /**
+   * Live x402 leaderboard — the sellers earning the most USDC (or serving the
+   * most calls) on Base in the last ~24h, derived from on-chain USDC
+   * transfers. Free; no payment, no wallet, no proof-of-work. Useful when
+   * building agents that want to discover the live x402 economy beyond a
+   * single service's catalog. Hourly snapshot — safe to call freely.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.limit=10]                  max rows (1-50)
+   * @param {"usd"|"calls"} [opts.sort="usd"]          rank by USDC settled or call count
+   * @param {"external"|"all"} [opts.include="external"] hide this service's own wallet (default) or include it
+   * @returns {Promise<{window:string, asOf:string, sort:string, include:string, totalSellers:number, results:Array<object>, source:string}>}
+   */
+  async topSellers({ limit = 10, sort = "usd", include = "external" } = {}) {
+    const top = Math.min(Math.max(parseInt(limit, 10) || 10, 1), 50);
+    const sortParam = sort === "calls" ? "calls" : "usd";
+    const includeParam = include === "all" ? "all" : "external";
+    const url = `${this.baseUrl}/api/leaderboard?top=${top}&sort=${sortParam}&include=${includeParam}`;
+    const r = await this.f(url);
+    if (!r.ok) throw new Error(`topSellers failed: HTTP ${r.status}`);
+    const snap = await r.json();
+    return {
+      window: snap.windowLabel || snap.windowServed || "24h",
+      asOf: snap.asOf,
+      sort: snap.sortServed || sortParam,
+      include: snap.include || includeParam,
+      totalSellers: snap.totalSellers ?? (snap.leaderboard || []).length,
+      results: snap.leaderboard || [],
+      ...(snap.warming || snap.scanSkipped ? { warming: true } : {}),
+      source: `${this.baseUrl}/api/leaderboard`,
+    };
+  }
+
+  /**
+   * 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;
@@ -145,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.2.1",
-  "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.0",
+  "description": "Buyer-side SDK for Agent402.Tools (x402): resolve a task to a tool across 1,338 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"
 }