agent402-client 0.2.1 → 0.3.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 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 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 |

package/index.js

@@ -77,6 +77,39 @@ 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`,
+    };
+  }
+
   /** Solve a proof-of-work challenge object (from a 402 body) into an X-Pow-Solution value. */
   static solvePow(pow) {
     let n = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.2.1",
+  "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.",
   "type": "module",
   "main": "index.js",