references/cli.md
# 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.
scripts/cli.mjs
#!/usr/bin/env node
// 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 (import.meta.url === `file://${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);
}
}
SKILL.md
---
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.