skillpp 0.1.0

package/skills/binance-web3/crypto-market-rank/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: crypto-market-rank
+description: |
+  Crypto market leaderboards — ranked aggregate feeds across the whole market:
+  social-hype/sentiment rank, trending / top-search / Binance Alpha / tokenized-stocks rank,
+  smart-money net-inflow rank (which tokens received the most inflow), top meme tokens by breakout score on Pulse launchpad,
+  top trader PnL leaderboard (ALL / KOL).
+  Use whenever the user wants a ranked list of tokens or addresses by some metric — phrases like
+  "trending tokens", "top N by hype", "leaderboard", "rank by X", "biggest inflows", "top traders this week".
+metadata:
+  author: binance-web3-team
+  version: "3.0"
+---
+
+# Crypto Market Rank Skill
+## Overview
+
+Five leaderboard / rank endpoints fronted by one CLI. The agent issues a subcommand with a JSON blob; the CLI owns URL paths, method selection , query-string building, and upstream error mapping. 
+
+## When to Use This Skill
+
+| User intent | Command |
+|-------------|---------|
+| Social Hype Leaderboard, Tokens with highest social buzz + sentiment summary | `social-hype` |
+| Unified Token Rank, Trending / Top Search / Alpha / Stock token lists (filtered) | `token-rank` |
+| Smart Money Inflow Rank, Tokens currently receiving the most smart-money net inflow | `smart-money-inflow` |
+| Meme Token Rank,Top meme tokens from Pulse launchpad (breakout score) | `meme-rank` |
+| Address Pnl Rank, Top trader PnL leaderboard (ALL / KOL) | `address-pnl-rank` |
+
+## Supported Chains
+
+| Chain | chainId | Supported on |
+|-------|---------|--------------|
+| BSC | `56` | `social-hype`, `token-rank`, `smart-money-inflow`, `meme-rank`, `address-pnl-rank` |
+| Solana | `CT_501` | `social-hype`, `token-rank`, `smart-money-inflow`, `address-pnl-rank` |
+| Base | `8453` | `social-hype`, `token-rank`, `smart-money-inflow`, `address-pnl-rank` |
+| Ethereum | `1` | `token-rank`, `address-pnl-rank` |
+
+> `meme-rank` only supports BSC (`56`). The CLI rejects unsupported chainIds with an error before calling the API.
+
+## How to Call APIs
+
+```bash
+node <skill-dir>/scripts/cli.mjs token-rank \
+  '{"rankType":10,"chainId":"56","period":50,"sortBy":70,"orderAsc":false,"page":1,"size":20}'
+```
+
+## Commands
+
+| Command | Purpose | Required args | Example |
+|---------|---------|---------------|---------|
+| `social-hype` | Social buzz leaderboard with sentiment + summaries | `chainId`, `targetLanguage`, `timeRange` | `node <skill-dir>/scripts/cli.mjs social-hype '{"chainId":"56","targetLanguage":"en","timeRange":1}'` |
+| `token-rank` | Unified rank (Trending / TopSearch / Alpha / Stock) with filters | `rankType`, `chainId` | `node <skill-dir>/scripts/cli.mjs token-rank '{"rankType":10,"chainId":"56","page":1,"size":20}'` |
+| `smart-money-inflow` | Token rank by smart money net inflow | `chainId` (CLI defaults `tagType` to `2`) | `node <skill-dir>/scripts/cli.mjs smart-money-inflow '{"chainId":"56","period":"24h"}'` |
+| `meme-rank` | Top 100 Pulse launchpad meme tokens scored for breakout | `chainId` | `node <skill-dir>/scripts/cli.mjs meme-rank '{"chainId":"56"}'` |
+| `address-pnl-rank` | Top trader PnL leaderboard | `chainId`, `period`, `tag` | `node <skill-dir>/scripts/cli.mjs address-pnl-rank '{"chainId":"CT_501","period":"30d","tag":"ALL","pageNo":1,"pageSize":25}'` |
+
+## Use Flow
+
+> **Before calling any API, you MUST read its reference file for the full command, parameters, example, and response fields.**
+
+1. **Select command** — match user intent to the "When to use" column above
+   - For token-rank, also decide `rankType`: `10`=Trending, `11`=TopSearch, `20`=Alpha, `40`=Stock, see rules below
+2. **Set chain** — pick `chainId` from Supported Chains; omit for all chains (token-rank only)
+3. **Set time window** (if applicable)
+   - social-hype: `timeRange=1` (24h)
+   - token-rank `period`: `10`=1m, `20`=5m, `30`=1h, `40`=4h, `50`=24h (default `50`)
+   - smart-money-inflow `period`: `5m` / `1h` / `4h` / `24h` (default `24h`)
+   - address-pnl-rank `period`: `7d` / `30d` / `90d` (default `30d`)
+4. **Set filters** — if user mentions specific conditions (market cap, volume, holders, PnL, win rate, etc.), read the reference for filter params
+5. **Read reference** — open the corresponding reference file for command, full params, example, and response fields
+6. **Call cli** — run the cli.mjs in scripts folder
+
+
+## Rules
+
+- **`rankType` enum for `token-rank`**: `10`=Trending, `11`=TopSearch, `20`=Alpha, `40`=Stock.
+  - **Trending (`10`) is the default.** Use it for any generic "hot / trending / popular / 热门 / 趋势 / 火" request — this is the board users mean 99% of the time.
+  - **TopSearch (`11`) requires an explicit signal.** Only pick it when the user says "热搜", "top search", "most searched", "搜索榜", or otherwise makes clear they want the search-count-driven list (not price/volume-driven). Search-count sort (`sortBy: 2`) only makes sense with TopSearch.
+  - When ambiguous, go Trending. Do not silently switch to TopSearch.
+- **`tagType` default for `smart-money-inflow`**: the CLI auto-fills `tagType: 2` (upstream requires it and `2` is the only supported value today). Callers do not need to pass it; if passed, the caller's value wins.
+- **`period` values differ by command**: `social-hype.timeRange` is numeric (`1`=24h); `token-rank.period` is a code (`10`=1m, `20`=5m, `30`=1h, `40`=4h, `50`=24h); `smart-money-inflow.period` is a string (`5m`/`1h`/`4h`/`24h`); `address-pnl-rank.period` is a string (`7d`/`30d`/`90d`). See `references/cli.md` for details.
+- **`token-rank` supports rich filters** (min/max pairs: `marketCap`, `volume`, `liquidity`, `holders`, `percentChange`, etc.). Pass them as flat top-level fields on the JSON body — the CLI forwards the body verbatim.
+- **Icon / logo URL prefix**: most `icon` / `logo` / `metaInfo.logo` / `tokenIconUrl` fields are relative paths. Prepend `https://bin.bnbstatic.com` to render. `chainLogoUrl` is already a full URL.
+- **Numeric fields arrive as strings** (`price`, `marketCap`, `percentChange*`, etc.) — convert before arithmetic.
+- **`address-pnl-rank.pageSize` cap is 25** — larger values are silently clamped.
+- **All timestamps are milliseconds.**
+
+## Full CLI Reference
+
+See [`references/cli.md`](references/cli.md) for per-subcommand invocations, parameter tables, return-field tables, sort-option and filter tables, and real response samples.

package/skills/binance-web3/crypto-market-rank/references/cli.md

@@ -0,0 +1,219 @@
+# crypto-market-rank — CLI Reference
+
+Complete reference for every command in `scripts/cli.mjs`.
+
+**Invocation pattern:** `node <skill-dir>/scripts/cli.mjs <command> '<json_params>'`
+**Exit codes:** `0` success · `1` usage/upstream error · `3` network failure
+
+**Supported chains:** BSC (`56`), Base (`8453`), Solana (`CT_501`). Per-command restrictions noted below.
+
+---
+
+## `social-hype` — Social buzz leaderboard
+
+```bash
+node <skill-dir>/scripts/cli.mjs social-hype '{"chainId":"56","targetLanguage":"en","timeRange":1}'
+```
+
+### Parameters
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `chainId` | string | **yes** | Chain identifier |
+| `targetLanguage` | string | **yes** | Translation target, e.g. `"en"`, `"zh"` |
+| `timeRange` | number | **yes** | Time range, `1` = 24h |
+| `sentiment` | string | no | Filter: `All` / `Positive` / `Negative` / `Neutral` |
+| `socialLanguage` | string | no | Content language, `"ALL"` for all |
+
+### Return fields (under `.data.leaderBoardList[]`)
+
+| Field Path | Type | Description |
+|---|---|---|
+| `metaInfo.symbol` / `metaInfo.logo` | string | Token symbol and icon path (prefix `https://bin.bnbstatic.com`) |
+| `metaInfo.chainId` / `metaInfo.contractAddress` | string | Chain + contract |
+| `metaInfo.tokenAge` | number | Creation timestamp (ms) |
+| `marketInfo.marketCap` / `marketInfo.priceChange` | number | Market cap (USD), 24h % change |
+| `socialHypeInfo.socialHype` | number | Total social hype index |
+| `socialHypeInfo.sentiment` | string | `Positive` / `Negative` / `Neutral` |
+| `socialHypeInfo.socialSummaryBrief` / `...Detail` | string | Social summary (short / detailed) |
+| `socialHypeInfo.socialSummaryBriefTranslated` / `...DetailTranslated` | string | Translated summaries |
+
+**Nested shape:** each entry is `{metaInfo, marketInfo, socialHypeInfo}` — fields grouped by the three objects above.
+
+---
+
+## `token-rank` — Unified token rank (POST)
+
+> ⚠️ `rankType` determines the list: `10`=Trending · `11`=TopSearch · `20`=Alpha · `40`=Stock.
+
+```bash
+node <skill-dir>/scripts/cli.mjs token-rank '{"rankType":10,"chainId":"56","page":1,"size":20}'
+```
+
+### Parameters (all optional; body is a JSON object)
+
+**Core:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `rankType` | integer | `10` | `10`=Trending, `11`=TopSearch, `20`=Alpha, `40`=Stock |
+| `chainId` | string | — | `"1"`, `"56"`, `"8453"`, `"CT_501"` |
+| `period` | integer | `50` | `10`=1m, `20`=5m, `30`=1h, `40`=4h, `50`=24h |
+| `sortBy` | integer | `0` | See Sort Options below |
+| `orderAsc` | boolean | `false` | Ascending if `true` |
+| `page` / `size` | integer | `1` / `200` | Pagination (size max 200) |
+
+**Min/Max filters (decimal unless noted):** `percentChange` · `marketCap` · `volume` · `liquidity` · `holders` (long) · `holdersTop10Percent` · `kycHolders` (long, Alpha only) · `count` (long) · `uniqueTrader` (long) · `launchTime` (long, ms).
+
+**Advanced filters:** `keywords` / `excludes` (string[]) · `socials` (int[]: `0`=at_least_one, `1`=X, `2`=Telegram, `3`=Website) · `alphaTagFilter` (string[]) · `auditFilter` (int[]: `0`=not_renounced, `1`=freezable, `2`=mintable) · `tagFilter` (int[]: `0`=hide_alpha, `23`=dex_paid, `29`=alpha_points, …).
+
+**Sort Options (`sortBy`):** `0`=Default · `1`=Web default · `2`=Search count · `10`=Launch time · `20`=Liquidity · `30`=Holders · `40`=Market cap · `50`=Price change · `60`=Tx count · `70`=Volume · `80`=KYC holders · `90`=Price · `100`=Unique traders.
+
+### Return fields (under `.data.tokens[]`)
+
+| Field | Type | Description |
+|---|---|---|
+| `chainId` / `contractAddress` / `symbol` / `icon` | string | Identity + logo (prefix `https://bin.bnbstatic.com`) |
+| `price` / `marketCap` / `liquidity` / `holders` | string | All USD string-encoded decimals |
+| `percentChange{1m,5m,1h,4h,24h}` | string | Price change per window (%) |
+| `volume{window}` / `volume{window}{Buy,Sell}` | string | Volume + direction breakdown |
+| `count{window}` / `count{window}{Buy,Sell}` | string | Transaction counts |
+| `uniqueTrader{window}` | string | Unique traders per window |
+| `alphaInfo` | object | Alpha metadata (`tagList`, `description`) |
+| `auditInfo` | object | Audit info (`riskLevel`, `riskNum`, `cautionNum`) |
+| `launchTime` / `decimals` | string / int | Launch timestamp (ms), token decimals |
+| `kycHolders` / `holdersTop10Percent` | string | KYC holder count, top-10 % |
+
+`.data.total` / `.data.page` / `.data.size` provide pagination context.
+
+---
+
+## `smart-money-inflow` — Smart money net inflow rank (POST)
+
+> ⚠️ **BSC (`56`) and Solana (`CT_501`) only.**
+> ⚠️ `tagType` defaults to `2` (the CLI injects it automatically if omitted — always the correct value).
+
+```bash
+node <skill-dir>/scripts/cli.mjs smart-money-inflow '{"chainId":"56","period":"24h"}'
+```
+
+### Parameters
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `chainId` | string | **yes** | `"56"` (BSC), `"CT_501"` (Solana) |
+| `period` | string | no | `"5m"` / `"1h"` / `"4h"` / `"24h"` |
+| `tagType` | integer | auto | Injected as `2` if omitted — upstream only accepts `2` |
+
+### Return fields (under `.data[]`)
+
+| Field | Type | Description |
+|---|---|---|
+| `tokenName` / `tokenIconUrl` | string | Name + icon path (prefix `https://bin.bnbstatic.com`) |
+| `ca` | string | Contract address |
+| `price` / `marketCap` / `volume` / `liquidity` | string | USD, string-encoded |
+| `priceChangeRate` | string | Price change in period (%) |
+| `holders` / `kycHolders` / `holdersTop10Percent` | string | Holder stats |
+| `count` / `countBuy` / `countSell` | string | Tx counts in period |
+| `inflow` | number | **Smart money net inflow (USD)** — primary ranking metric |
+| `traders` | integer | Number of smart-money addresses trading this token |
+| `launchTime` | number | Launch timestamp (ms) |
+| `tokenDecimals` | integer | Token decimals |
+| `tokenRiskLevel` | integer | `-1`=unknown, `1`=low, `2`=medium, `3`=high |
+| `link` | array | `[{label, link}]` social links |
+| `tokenTag` | object | Tags by category |
+
+---
+
+## `meme-rank` — Top meme tokens from Pulse launchpad
+
+> ⚠️ **BSC (`56`) only.** Returns top 100 meme tokens launched via Pulse, scored and ranked by a breakout-potential algorithm.
+
+```bash
+node <skill-dir>/scripts/cli.mjs meme-rank '{"chainId":"56"}'
+```
+
+### Parameters
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `chainId` | string | **yes** | Must be `"56"` (BSC) |
+
+### Return fields (under `.data.tokens[]`)
+
+| Field | Type | Description |
+|---|---|---|
+| `rank` / `score` | integer / string | Rank position and algorithm score (higher = stronger breakout signal) |
+| `chainId` / `contractAddress` / `symbol` | string | Identity |
+| `metaInfo.icon` / `metaInfo.name` / `metaInfo.decimals` | — | Logo path, full name, decimals |
+| `metaInfo.aiNarrativeFlag` | int | `1` = AI narrative summary available |
+| `price` / `percentChange` / `percentChange7d` | string | Current price, current %, 7-day % |
+| `marketCap` / `liquidity` / `volume` | string | USD |
+| `volumeBnTotal` / `volumeBn7d` | string | Binance-user volume (total / 7d) |
+| `holders` / `kycHolders` / `bnUniqueHolders` / `holdersTop10Percent` | string | Holder stats |
+| `count` / `countBnTotal` / `countBn7d` | integer | Transaction counts |
+| `uniqueTraderBn` / `uniqueTraderBn7d` | integer | Binance unique traders |
+| `impression` | integer | View count |
+| `createTime` / `migrateTime` | number | Creation + migration timestamps (ms) |
+| `alphaStatus` | integer | Alpha listing status |
+| `previewLink` | object | `{website[], x[], telegram[]}` |
+| `tokenTag` | object | Tags by category |
+
+---
+
+## `address-pnl-rank` — Top trader PnL leaderboard
+
+> ⚠️ **Chain support:** `"56"` (BSC), `"CT_501"` (Solana).
+> ⚠️ **`period` accepted values:** `"7d"` / `"30d"` / `"90d"`.
+> ⚠️ `pageSize` max = `25`.
+
+```bash
+node <skill-dir>/scripts/cli.mjs address-pnl-rank '{"chainId":"CT_501","period":"30d","tag":"ALL","pageNo":1,"pageSize":25}'
+```
+
+### Parameters
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `chainId` | string | **yes** | `"56"` or `"CT_501"` |
+| `period` | string | **yes** | `"7d"` / `"30d"` / `"90d"` |
+| `tag` | string | **yes** | `"ALL"` or `"KOL"` |
+| `sortBy` | integer | no | Sort field |
+| `orderBy` | integer | no | Order direction |
+| `pageNo` | integer | no | Min 1 |
+| `pageSize` | integer | no | Max 25 |
+
+**Min/Max filters:** `PNL` (decimal) · `winRate` (decimal, e.g. `1` = 1%) · `tx` (long) · `volume` (decimal).
+
+### Return fields (under `.data.data[]`)
+
+| Field | Type | Description |
+|---|---|---|
+| `address` / `addressLogo` / `addressLabel` | string | Wallet, avatar, display name |
+| `balance` | string | On-chain native coin balance (chain-native gas token) |
+| `tags` / `genericAddressTagList` | array | Tag info (e.g. KOL; detailed version has `tagName`, `logoUrl`, `extraInfo`) |
+| `realizedPnl` / `realizedPnlPercent` | string | Period PnL in USD and % |
+| `dailyPNL` | array | `[{realizedPnl, dt}]` per-day breakdown |
+| `winRate` | string | Win rate for the period |
+| `totalVolume` / `buyVolume` / `sellVolume` / `avgBuyVolume` | string | Volume breakdown (USD) |
+| `totalTxCnt` / `buyTxCnt` / `sellTxCnt` | integer | Transaction counts |
+| `totalTradedTokens` | integer | Number of distinct tokens traded |
+| `topEarningTokens` | array | `[{tokenAddress, tokenSymbol, tokenUrl, realizedPnl, profitRate}]` |
+| `tokenDistribution` | object | `{gt500Cnt, between0And500Cnt, between0AndNegative50Cnt, ltNegative50Cnt}` |
+| `lastActivity` | number | Last activity timestamp (ms) |
+
+Pagination: `.data.current` / `.data.size` / `.data.pages`. `dailyPNL[]` entries are `{realizedPnl, dt}`. `topEarningTokens[]` entries are `{tokenAddress, tokenSymbol, tokenUrl, realizedPnl, profitRate}`.
+
+---
+
+## Errors
+
+Exit codes: `0` ok · `1` upstream/usage (stderr: reason; stdout: body with business `code`) · `3` network.
+Business `code`: `000000` ok · `100004` rate-limited · `100002` bad param · `000400` token not found / unsupported chain.
+
+---
+
+## Notes
+
+- Icon URL prefix: `https://bin.bnbstatic.com` + `icon`/`logo`/`tokenIconUrl`.
+- Most price / volume / market-cap fields are string-encoded decimals — parse before arithmetic.

package/skills/binance-web3/crypto-market-rank/scripts/cli.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "url";
+// crypto-market-rank CLI - self-contained, zero-dep, Node >= 22
+// Usage: node cli.mjs <command> '<json_params>'
+//
+// Commands:
+//   social-hype         GET   social buzz leaderboard (sentiment + summary)
+//   token-rank          POST  unified rank (Trending / TopSearch / Alpha / Stock)
+//   smart-money-inflow  POST  token rank by smart money net inflow
+//   meme-rank           GET   top meme tokens from Pulse launchpad (BSC only)
+//   address-pnl-rank    GET   top trader PnL leaderboard
+//
+
+// ---- inline HTTP helper (self-contained, zero dependency) ----
+const TIMEOUT_MS = 10_000;
+const UA = { 'Accept-Encoding': 'identity', 'User-Agent': 'binance-web3/3.0 (Skill)' };
+
+const qs = (p) => Object.entries(p)
+  .filter(([, v]) => v != null)
+  .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+  .join('&');
+
+async function call({ url, method = 'GET', body, headers = {} }) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  const opts = { method, headers: { ...UA, ...headers }, signal: ctrl.signal };
+  if (method === 'POST') { opts.headers['content-type'] = 'application/json'; opts.body = JSON.stringify(body || {}); }
+  let res;
+  try { res = await fetch(url, opts); }
+  catch { clearTimeout(timer); throw Object.assign(new Error('Network request failed'), { exitCode: 3 }); }
+  clearTimeout(timer);
+  const data = await res.json();
+  if (res.status >= 400) throw Object.assign(new Error(`HTTP ${res.status}`), { exitCode: 1, body: data });
+  return data;
+}
+
+// ---- per-command supported chains (client-side fail-fast) ----
+const CHAINS = {
+  'social-hype':        new Set(['56', '8453', 'CT_501']),
+  'token-rank':         new Set(['56', '8453', 'CT_501', '1']),
+  'smart-money-inflow': new Set(['56', 'CT_501', '8453']),
+  'meme-rank':          new Set(['56']),
+  'address-pnl-rank':   new Set(['56', 'CT_501', '8453', '1']),
+};
+
+function validateChainId(cmd, chainId) {
+  const allowed = CHAINS[cmd];
+  if (!allowed) return;
+  const id = String(chainId ?? '');
+  if (!allowed.has(id)) {
+    const supported = [...allowed].map((c) => `"${c}"`).join(', ');
+    throw Object.assign(
+      new Error(`${cmd}: unsupported chainId "${chainId}". Supported: ${supported}`),
+      { exitCode: 1 },
+    );
+  }
+}
+
+// ---- commands: (params) => { url, method?, body?, headers? } ----
+const COMMANDS = {
+  'social-hype': (p) => {
+    validateChainId('social-hype', p.chainId);
+    return {
+      url: `https://web3.binance.com/bapi/defi/v1/public/wallet-direct/buw/wallet/market/token/pulse/social/hype/rank/leaderboard/ai?${qs(p)}`,
+    };
+  },
+  'token-rank': (p) => {
+    validateChainId('token-rank', p.chainId);
+    const TRENDING_ALPHA_DEFAULTS = {
+      countMin: 10,
+      launchTimeMin: 15,
+      liquidityMin: 5000,
+      uniqueTraderMin: 10,
+      volumeMin: 10000,
+    };
+    const TRENDING_DEFAULTS = {
+      tagFilter: [1, 2, 3],
+    };
+
+    const rankType = p.rankType ?? 10;
+    let body = { ...p };
+
+    if (rankType === 10) {
+      // Trending: apply both shared + trending-only defaults (caller params take precedence)
+      body = { ...TRENDING_ALPHA_DEFAULTS, ...TRENDING_DEFAULTS, ...p };
+    } else if (rankType === 20) {
+      // Alpha: apply only shared defaults (caller params take precedence)
+      body = { ...TRENDING_ALPHA_DEFAULTS, ...p };
+    }
+
+    return {
+      url: 'https://web3.binance.com/bapi/defi/v1/public/wallet-direct/buw/wallet/market/token/pulse/unified/rank/list/ai',
+      method: 'POST',
+      body,
+    };
+  },
+  'smart-money-inflow': (p) => {
+    validateChainId('smart-money-inflow', p.chainId);
+    return {
+      url: 'https://web3.binance.com/bapi/defi/v1/public/wallet-direct/tracker/wallet/token/inflow/rank/query/ai',
+      method: 'POST',
+      body: { ...p, tagType: p.tagType ?? 2 },
+    };
+  },
+  'meme-rank': (p) => {
+    validateChainId('meme-rank', p.chainId);
+    return {
+      url: `https://web3.binance.com/bapi/defi/v1/public/wallet-direct/buw/wallet/market/token/pulse/exclusive/rank/list/ai?${qs(p)}`,
+    };
+  },
+  'address-pnl-rank': (p) => {
+    validateChainId('address-pnl-rank', p.chainId);
+    return {
+      url: `https://web3.binance.com/bapi/defi/v1/public/wallet-direct/market/leaderboard/query/ai?${qs(p)}`,
+    };
+  },
+};
+
+// ---- exports (for unit testing; direct execution still works - see dispatch below) ----
+export { COMMANDS, call, qs, UA, TIMEOUT_MS, CHAINS, validateChainId };
+
+// ---- CLI dispatch (only runs when executed directly, not when imported) ----
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  const [cmd, paramsStr] = process.argv.slice(2);
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log("Usage: node cli.mjs <command> '<json_params>'\n\nCommands:");
+    for (const name of Object.keys(COMMANDS)) console.log(`  ${name}`);
+    process.exit(0);
+  }
+
+  const builder = COMMANDS[cmd];
+  if (!builder) { console.error(`Unknown command: ${cmd}\nRun with --help to see available commands.`); process.exit(1); }
+
+  let params = {};
+  if (paramsStr) {
+    try { params = JSON.parse(paramsStr); }
+    catch { console.error('Invalid JSON params'); process.exit(1); }
+  }
+
+  try {
+    const result = await call(builder(params));
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(err.message);
+    if (err.body) console.log(JSON.stringify(err.body, null, 2));
+    process.exit(err.exitCode || 1);
+  }
+}

package/skills/binance-web3/meme-rush/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: meme-rush
+description: |
+  Live launchpad feed + AI hot topics for meme tokens.
+  (1) meme-rush: real-time lifecycle feed on launchpads (Pump.fun, Four.meme) — brand-new launches,
+  currently-finalizing / bonding-curve tokens, and just-migrated-to-DEX tokens; filter by dev behavior, age, market cap.
+  (2) topic-rush: AI-detected hot market narratives with the associated tokens ranked by inflow.
+  Use for: "new pump.fun launches", "what just migrated", "currently bonding", "hot narratives", "what topic is pumping right now",
+  "live launchpad feed", "AI hot topics".
+metadata:
+  author: binance-web3-team
+  version: "2.0"
+---
+
+# Meme Rush Skill
+
+## Overview
+
+Two rank feeds fronted by one CLI: `meme-rush` (launchpad lifecycle tracking) and `topic-rush` (AI hot-topic discovery with associated tokens). The CLI owns URL, method, JSON encoding, timeout, and upstream error mapping — the agent only picks the subcommand and fills the filter JSON.
+
+## When to Use This Skill
+
+| User intent | Command |
+|-------------|---------|
+| New / finalizing / migrated meme tokens on a launchpad | `meme-rush` |
+| AI-generated market hot topics and their associated tokens | `topic-rush` |
+
+## Supported Chains
+
+| Chain | chainId | Supported on |
+|-------|---------|--------------|
+| BSC | `56` | `meme-rush`, `topic-rush` |
+| Solana | `CT_501` | `meme-rush`, `topic-rush` |
+| Base | `8453` | `meme-rush` |
+
+## How to Call APIs
+
+```bash
+node <skill-dir>/scripts/cli.mjs meme-rush '{"chainId":"CT_501","rankType":10,"limit":20}'
+node <skill-dir>/scripts/cli.mjs topic-rush '{"chainId":"CT_501","rankType":10,"sort":10,"asc":false}'
+```
+
+## Commands
+
+| Command | Purpose | Required args | Example |
+|---------|---------|---------------|---------|
+| `meme-rush` | Launchpad token lifecycle ranking (new / finalizing / migrated) | `chainId`, `rankType` | `node <skill-dir>/scripts/cli.mjs meme-rush '{"chainId":"CT_501","rankType":10,"limit":20}'` |
+| `topic-rush` | AI-generated hot topics with associated tokens | `chainId`, `rankType`, `sort` | `node <skill-dir>/scripts/cli.mjs topic-rush '{"chainId":"CT_501","rankType":10,"sort":10}'` |
+
+Optional filters for `meme-rush` (all min/max pairs): `progress`, `tokenAge`, `holders`, `liquidity`, `volume`, `marketCap`, `count{,Buy,Sell}`, `holders{Top10,Dev,Sniper,Insider}Percent`, `bundlerHoldingPercent`, `newWalletHoldingPercent`, `bnHoldingPercent`, `{bn,kol,pro}Holders`, `devMigrateCount`, `globalFee`; plus `keywords`, `excludes`, `limit` (max 200), `protocol[]`, `devPosition`, `devBurnedToken`, `excludeDevWashTrading`, `excludeInsiderWashTrading`, `exclusive`, `paidOnDexScreener`, `pumpfunLiving`, `cmcBoost`, `pairAnchorAddress[]`, `tokenSocials.atLeastOne`, `tokenSocials.socials[]`. See `references/cli.md` for type and semantics of each field.
+
+Optional filters for `topic-rush`: `asc` (boolean), `keywords`, `topicType`, `tokenSizeMin/Max`, `netInflowMin/Max`.
+
+## Rules
+
+- **`meme-rush` `rankType`** enum — stage of the token's launchpad lifecycle:
+  - `10` = **New** (freshly created, still on bonding curve)
+  - `20` = **Finalizing** (bonding curve nearly complete, about to migrate)
+  - `30` = **Migrated** (just migrated to DEX)
+- **`topic-rush` `rankType`** enum — topic freshness:
+  - `10` = **Latest** (newest hot topics)
+  - `20` = **Rising** (rising topics, all-time-high inflow between $1k–$20k)
+- **`topic-rush` `sort`** enum: `10` = create time, `20` = net inflow. **Default to `sort=10`** when the user does not specify a sort preference.
+- **Only `chainId` and `rankType` are required** for `meme-rush`; all other parameters are optional filters. `topic-rush` additionally requires `sort`.
+- **Percentage fields are pre-formatted** — `progress`, holder %, `devSellPercent`, `taxRate`, `priceChange`, `priceChange24h` are already strings like `"42.5"`, so **append `%` directly** when displaying; do NOT multiply by 100.
+- **Icon URL prefix**: `icon` is a relative path returned by upstream; prepend `https://bin.bnbstatic.com` before rendering. `tokenList[].icon` in `topic-rush` responses follows the same rule.
+- **`taxRate` visibility**: for `protocol=2001` (Four.meme) `taxRate` only appears on the **Migrated** list; for `protocol=2002` (Flap) it appears on all lists.
+- **Protocol codes** (`1001`–`2002`) map to specific launchpads (Pump.fun, Moonit, Pump AMM, Raydium V4/CPMM/CLMM, BONK, Dynamic BC, Moonshot, Jup Studio, Bags, Believer, Meteora DAMM V2 / Pools, Orca, Four.meme, Flap). See `references/cli.md` for the full table.
+
+## Full CLI Reference
+
+See [`references/cli.md`](references/cli.md) for per-subcommand invocations, full parameter tables (all filter fields, holder-distribution filters, dev & launch filters), return-field tables (core, trade counts, holder distribution, dev & migration, tags & flags, social links, AI narrative, topic + tokenList), and real response samples.