madeonsol 1.8.0 → 1.9.1

package/README.md

@@ -7,16 +7,18 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 
 Official TypeScript/JavaScript SDK for the **[MadeOnSol](https://madeonsol.com) Solana API** — zero dependencies, fully typed, works in Node.js ≥ 18 and edge runtimes.
-n> Real-time Solana trading intelligence: track 1,000+ KOL wallets with <3s latency, score 6,700+ Pump.fun deployers by reputation, detect multi-KOL coordination signals, and stream every DEX trade. Free tier: 200 requests/day at [madeonsol.com/developer](https://madeonsol.com/developer) — no credit card required.
+> Real-time Solana trading intelligence: track 1,000+ KOL wallets with <3s latency, score 6,700+ Pump.fun deployers by reputation, detect multi-KOL coordination signals, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day at [madeonsol.com/developer](https://madeonsol.com/developer) — no credit card required.
 
 > **Build Solana trading bots, analytics dashboards, KOL copy-trading tools, deployer sniper bots, and ecosystem browsers.**
 
 | Feature | Description |
 |---|---|
-| **KOL Tracker** | Real-time trade feed, PnL leaderboard with five time windows (today, 7d, 30d, 90d, 180d), coordination detection, and per-wallet profiles for 1,000+ tracked KOL wallets. **180 days of trade history** retained. |
+| **KOL Tracker** | Real-time trade feed, PnL leaderboard with five time windows (today, 7d, 30d, 90d, 180d), coordination detection, per-wallet profiles, and deep PnL analytics for 1,000+ tracked KOL wallets. **180 days of trade history** retained. |
+| **Alpha Wallet Intel** | Leaderboard of 47,000+ scored early-buyer wallets, full wallet profiles, linked-wallet clustering, token cap-table enrichment, and 0–100 buyer quality scores. |
+| **Wallet Tracker** | Monitor any Solana wallet for swaps and transfers. Track up to 10/50/100 wallets (BASIC/PRO/ULTRA). 120-day event retention. WS events on ULTRA. |
 | **Deployer Hunter** | Pump.fun deployer scoring, tier leaderboard, deploy alerts, and bonding intelligence |
 | **DEX Trade Stream** | Real-time WebSocket stream of ALL Solana DEX trades — filter by token, wallet, program, or trade size (Ultra) |
-| **Webhooks** | Push notifications for KOL trades, coordination signals, and deployer alerts (Pro/Ultra) |
+| **Webhooks** | Push notifications for KOL trades, coordination signals, deployer alerts, and wallet tracker events (Pro/Ultra) |
 | **Tool Directory** | Search 950+ Solana tools and dApps indexed on MadeOnSol |
 
 **Links:** [Full docs](https://madeonsol.com/solana-api) · [Website](https://madeonsol.com) · [API docs](https://madeonsol.com/api-docs)
@@ -154,6 +156,186 @@ Returns: `KolTokenActivity`
 
 ---
 
+#### `client.kol.pnl(wallet, params?)`
+
+Deep per-wallet PnL breakdown with equity curve, risk metrics, and position history.
+
+```ts
+const pnl = await client.kol.pnl("7xKX...", {
+  period: "30d", // "7d" | "30d" | "90d" | "180d", default "30d"
+});
+// BASIC: summary stats only
+// PRO: + equity curve + closed positions
+// ULTRA: + open positions
+```
+
+Returns: `KolPnlResponse`
+
+---
+
+#### `client.kol.trendingTokens(params?)`
+
+Tokens ranked by KOL buy volume across multiple time windows.
+
+```ts
+const { tokens } = await client.kol.trendingTokens({
+  period: "1h",    // "5m" | "15m" | "30m" | "1h" | "4h" | "8h" | "12h", default "1h"
+  min_kols: 2,     // minimum distinct KOL buyers
+  limit: 20,       // 1–50, default 20
+});
+// Sub-hour periods (5m, 15m, 30m) require PRO or ULTRA
+```
+
+Returns: `KolTrendingTokensResponse`
+
+---
+
+### Alpha Wallet Intelligence — `client.alpha`
+
+#### `client.alpha.leaderboard(params?)`
+
+Leaderboard of 47,000+ scored early-buyer wallets ranked by win rate, PnL, or ROI.
+
+```ts
+const { wallets } = await client.alpha.leaderboard({
+  period: "30d",   // "7d" | "30d" | "90d", default "30d"
+  sort: "win_rate", // "win_rate" | "pnl" | "roi"
+  min_tokens: 5,
+  exclude_bots: true,
+});
+// BASIC: 25 results, PRO: 100, ULTRA: 500
+```
+
+Returns: `AlphaLeaderboardResponse`
+
+---
+
+#### `client.alpha.wallet(wallet)`
+
+Full profile for an alpha wallet including per-token history and bot signals. ULTRA only.
+
+```ts
+const profile = await client.alpha.wallet("7xKX...");
+```
+
+Returns: `AlphaWalletResponse`
+
+---
+
+#### `client.alpha.linked(wallet)`
+
+Linked-wallet clustering — wallets that co-bought with this address within 2 seconds. ULTRA only.
+
+```ts
+const { linked } = await client.alpha.linked("7xKX...");
+```
+
+Returns: `AlphaLinkedResponse`
+
+---
+
+#### `client.alpha.capTable(mint)`
+
+First buyers for a token enriched with historical win rates, PnL, and KOL identity. PRO/ULTRA.
+
+```ts
+const { buyers } = await client.alpha.capTable("EPjFW...");
+```
+
+Returns: `AlphaCapTableResponse`
+
+---
+
+#### `client.alpha.buyerQuality(mint)`
+
+0–100 cohort quality score based on the profile of a token's first buyers. All tiers. 5-minute cache.
+
+```ts
+const { score } = await client.alpha.buyerQuality("EPjFW...");
+```
+
+Returns: `AlphaBuyerQualityResponse`
+
+---
+
+### Wallet Tracker — `client.walletTracker`
+
+#### `client.walletTracker.watchlist()`
+
+List your tracked wallets and remaining capacity.
+
+```ts
+const { wallets, capacity } = await client.walletTracker.watchlist();
+// capacity: { used, limit } — BASIC: 10, PRO: 50, ULTRA: 100
+```
+
+Returns: `WatchlistResponse`
+
+---
+
+#### `client.walletTracker.addToWatchlist(wallet, params?)`
+
+Add a wallet to your watchlist. Tracking begins immediately.
+
+```ts
+await client.walletTracker.addToWatchlist("7xKX...", { label: "whale" });
+```
+
+---
+
+#### `client.walletTracker.removeFromWatchlist(wallet)`
+
+Remove a wallet from your watchlist.
+
+```ts
+await client.walletTracker.removeFromWatchlist("7xKX...");
+```
+
+---
+
+#### `client.walletTracker.updateLabel(wallet, label)`
+
+Update the label for a tracked wallet.
+
+```ts
+await client.walletTracker.updateLabel("7xKX...", "smart money");
+```
+
+---
+
+#### `client.walletTracker.trades(params?)`
+
+Historical swap and transfer events for your watched wallets. 120-day retention.
+
+```ts
+const { events } = await client.walletTracker.trades({
+  wallet: "7xKX...",    // filter by specific wallet
+  action: "buy",        // "buy" | "sell"
+  event_type: "swap",   // "swap" | "transfer"
+  limit: 50,
+  before: "2026-04-01T00:00:00Z", // ISO 8601 cursor
+});
+```
+
+Returns: `WalletTrackerTradesResponse`
+
+---
+
+#### `client.walletTracker.summary(params?)`
+
+Per-wallet stats across your watchlist: swap counts, SOL bought/sold, last event time.
+
+```ts
+const { wallets } = await client.walletTracker.summary({
+  period: "7d",        // "24h" | "7d" | "30d", default "7d"
+  wallet: "7xKX...",  // optional: single wallet
+});
+```
+
+Returns: `WalletTrackerSummaryResponse`
+
+---
+
 ### Deployer Hunter — `client.deployer`
 
 #### `client.deployer.stats()`
@@ -303,16 +485,104 @@ console.log(token.dex_ws_url);  // wss://madeonsol.com/ws/v1/dex-stream (Ultra o
 
 Returns: `StreamToken` — `{ token, expires_at, ws_url, dex_ws_url?, usage }`
 
-**DEX Trade Stream (Ultra):** Connect to `dex_ws_url` and subscribe with filters:
+---
+
+### DEX Firehose (Ultra) — `wss://madeonsol.com/ws/v1/dex-stream`
+
+Real-time trades across **9+ Solana DEX programs** (Pump.fun, PumpAMM, PumpSwap, Raydium AMM/CPMM/CAMM, Jupiter v6, Orca Whirlpool, Meteora DBC/DAMM, LaunchLab/bonk.fun) on a single normalized WebSocket. Server-side filters drop everything you don't care about before it hits your socket.
+
+**Limits:** ULTRA = 2 connections, **10 named subscriptions per connection**, up to **500 trades replay** from in-memory ring buffer. Inbound rate limit: 5 messages/sec (excess emits one error per second).
+
+#### Quick start
+
+```ts
+import { WebSocket } from "ws"; // or native WebSocket in browsers/Bun
+
+const { token, dex_ws_url } = await client.stream.getToken();
+const ws = new WebSocket(`${dex_ws_url}?token=${token}`);  // token MUST be appended as query param
+
+ws.on("open", () => {
+  // Multi-subscription: each sub has its own sub_id and filters
+  ws.send(JSON.stringify({
+    type: "subscribe",
+    sub_id: "fresh-pumpfun",
+    replay: 50,                   // backfill up to 500 from ring buffer
+    filters: {
+      dex: "pumpfun",
+      token_age_max_seconds: 300, // first seen in last 5 min
+      min_sol: 0.5,
+      action: "buy",
+    },
+  }));
+});
+
+ws.on("message", (raw) => {
+  const msg = JSON.parse(raw.toString());
+  if (msg.channel === "dex:trades") {
+    // { sub_id, data: { wallet, mint, action, sol_amount, token_amount, dex, ... }, replay, ts }
+    console.log(msg.sub_id, msg.data.dex, msg.data.action, msg.data.sol_amount);
+  }
+});
+```
+
+#### Protocol — client → server
+
+| `type` | Required fields | Notes |
+|---|---|---|
+| `subscribe` | `sub_id`, `filters` | Optional `replay: 1–500` |
+| `update` | `sub_id`, `filters` | Replaces filters in place — no disconnect needed |
+| `unsubscribe` | `sub_id` | Or omit `sub_id` to clear all subs |
+| `list` | — | Server replies with `{ type: "list", subs: [...] }` |
+| `ping` | — | Heartbeat — server replies `{ type: "pong" }` |
+
+#### Server → client message shapes
 
 ```ts
-ws.send(JSON.stringify({
-  type: "subscribe",
-  filters: { program: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", min_sol: 0.5 }
-}));
-// Filters: token_mint, token_mints (max 50), wallet, wallets (max 50), program, min_sol, max_sol, action
+{ type: "connected",    tier: "ULTRA", capabilities: { max_subs: 10, max_replay: 500, dex_names: [...], deployer_tiers: [...] } }  // on connect
+{ type: "subscribed",   sub_id: "fresh-pumpfun", filters: { ... } }
+{ type: "replay_done",  sub_id: "fresh-pumpfun", count: 50 }              // after backfill
+{ type: "updated",      sub_id: "fresh-pumpfun", filters: { ... } }
+{ type: "unsubscribed", sub_id: "fresh-pumpfun" }
+{ type: "list",         subs: [{ sub_id, filters }] }                     // reply to { type: "list" }
+{ type: "heartbeat",    ts: 1712160000000 }                               // every 30s
+{ type: "error",        sub_id?, message: "..." }
+{ channel: "dex:trades", sub_id, data: { ... }, replay: false, ts: 1712160000000 }
 ```
 
+#### Filter dimensions
+
+At least **one targeting filter** is required (otherwise the firehose would dump every trade). Filters compose with AND semantics.
+
+| Filter | Type | Notes |
+|---|---|---|
+| `token_mint` / `token_mints` | string / string[] (≤50) | Targeting |
+| `wallet` / `wallets` | string / string[] (≤50) | Targeting |
+| `dex` | string \| string[] | `pumpfun`, `pumpamm`, `pumpswap`, `raydium`, `jupiter`, `orca`, `meteora`, `launchlab` |
+| `program` | string | Raw program ID |
+| `deployer_tier` | string \| string[] | `elite`, `good`, `moderate`, `rising`, `cold`, `unranked` (uses Deployer Hunter scoring) |
+| `token_age_max_seconds` | number | Only trades on mints first seen within window (uses persisted first-seen table) |
+| `market_cap_min_sol` / `market_cap_max_sol` | number | Bounded by current market cap (last trade price × cached supply, 1h TTL) |
+| `min_sol` / `max_sol` | number | Trade size bounds |
+| `action` | `"buy"` \| `"sell"` | Direction |
+
+**Async filters** (`token_age`, `deployer_tier`, `market_cap`) evaluate against live state and are **skipped on replay**. The first trade for an unseen mint may be skipped while the supply fetch is in flight.
+
+#### Multi-sub example
+
+```ts
+ws.send(JSON.stringify({ type: "subscribe", sub_id: "snipers",  filters: { token_age_max_seconds: 60 } }));
+ws.send(JSON.stringify({ type: "subscribe", sub_id: "whales",   filters: { min_sol: 50 } }));
+ws.send(JSON.stringify({ type: "subscribe", sub_id: "kol-mints", filters: { token_mints: ["EPjF...", "So11..."] } }));
+
+// Tighten the snipers filter without disconnecting
+ws.send(JSON.stringify({ type: "update", sub_id: "snipers", filters: { token_age_max_seconds: 30, min_sol: 0.3 } }));
+
+// Drop whales when you're done
+ws.send(JSON.stringify({ type: "unsubscribe", sub_id: "whales" }));
+```
+
+Each `dex:trades` message echoes the `sub_id` that matched, so you can route them locally without reapplying filter logic client-side.
+
 ---
 
 ### Webhooks — `client.webhooks`
@@ -406,6 +676,26 @@ import type {
   ToolsSearchResponse,
   Tool,
 
+  // KOL PnL & Trending
+  KolPnlResponse,
+  KolTrendingTokensResponse,
+  TrendingToken,
+
+  // Alpha Wallet Intelligence
+  AlphaWalletEntry,
+  AlphaLeaderboardResponse,
+  AlphaWalletResponse,
+  AlphaLinkedResponse,
+  AlphaCapTableResponse,
+  AlphaBuyerQualityResponse,
+
+  // Wallet Tracker
+  WalletEntry,
+  WatchlistResponse,
+  WalletTrackerEvent,
+  WalletTrackerTradesResponse,
+  WalletTrackerSummaryResponse,
+
   // Streaming
   StreamToken,
 
@@ -434,6 +724,15 @@ import type {
 - [API documentation](https://madeonsol.com/solana-api) — Interactive endpoint reference
 - [MadeOnSol on GitHub](https://github.com/LamboPoewert/madeonsol) — Main project repository
 
+## Also Available
+
+| Platform | Package |
+|---|---|
+| Python (LangChain, CrewAI) | [`madeonsol-x402`](https://pypi.org/project/madeonsol-x402/) on PyPI |
+| MCP Server (Claude, Cursor) | [`mcp-server-madeonsol`](https://www.npmjs.com/package/mcp-server-madeonsol) |
+| ElizaOS | [`@madeonsol/plugin-madeonsol`](https://www.npmjs.com/package/@madeonsol/plugin-madeonsol) |
+| Solana Agent Kit | [`solana-agent-kit-plugin-madeonsol`](https://www.npmjs.com/package/solana-agent-kit-plugin-madeonsol) |
+
 ---
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madeonsol",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Official SDK for the MadeOnSol Solana API — KOL wallet tracking, Pump.fun deployer intelligence, and tool directory",
   "type": "module",
   "main": "dist/index.js",