trading-signal

# trading-signal — 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

---

## `smart-money` — On-chain Smart Money trading signals

> ⚠️ Only `"56"` (BSC) and `"CT_501"` (Solana) are supported. `pageSize` max is `100`. Signals with `status: "timeout"` are stale — prefer `"valid"` / `"active"` signals.

```bash
node <skill-dir>/scripts/cli.mjs smart-money '{"chainId":"CT_501","page":1,"pageSize":20}'
```

### Parameters

| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| `chainId` | string | **yes** | — | `"56"` (BSC) · `"CT_501"` (Solana) |
| `page` | number | no | `1` | Page number (1-indexed) |
| `pageSize` | number | no | — | Items per page, max `100` |
| `smartSignalType` | string | no | — | Filter by signal type (e.g. `"SMART_MONEY"`); omit for all |

### Return fields (under `.data[]`)

**Token identity**

| Field | Type | Description |
|---|---|---|
| `signalId` | number | Unique signal ID |
| `ticker` | string | Token symbol |
| `chainId` | string | Chain identifier |
| `contractAddress` | string | Token contract address |
| `logoUrl` | string | Logo path — prefix with `https://bin.bnbstatic.com` |
| `chainLogoUrl` | string | Full URL of the chain icon |
| `tokenDecimals` | number | Token decimals |

**Tags & flags**

| Field | Type | Description |
|---|---|---|
| `isAlpha` | boolean | Marked as Alpha token |
| `launchPlatform` | string | Launch platform (e.g. `"Pumpfun"`, `"Moonshot"`) |
| `tokenTag` | object | Categorized tags. Known categories: `"Social Events"`, `"Launch Platform"`, `"Sensitive Events"`, `"Wash Trading Behavior"` |

**Signal data**

| Field | Type | Description |
|---|---|---|
| `smartSignalType` | string | e.g. `"SMART_MONEY"` |
| `direction` | string | `"buy"` or `"sell"` |
| `smartMoneyCount` | number | Smart money addresses triggering the signal (higher = stronger) |
| `signalCount` | number | Historical signal count for this token |
| `signalTriggerTime` | number | Signal trigger timestamp (ms) |
| `timeFrame` | number | Observation window (ms) |

**Price & performance**

| Field | Type | Description |
|---|---|---|
| `alertPrice`, `alertMarketCap` | string | Price / market cap at trigger (USD) |
| `currentPrice`, `currentMarketCap` | string | Latest price / market cap (USD) |
| `highestPrice`, `highestPriceTime` | string, number | Peak after signal + timestamp (ms) |
| `totalTokenValue` | string | Aggregate trade value at signal (USD) |
| `maxGain` | string | Max % gain since trigger — **decimal fraction** (e.g. `"0.25"` = 25%); multiply by 100 when displaying as a percentage |
| `exitRate` | number | % of smart money already exited (high = stale) |
| `status` | string | Signal status. Values: `active` (monitoring), `valid` (fresh/open), `timeout` (expired), `completed` (closed). |

**Sample `tokenTag` shape** (categorized; each category holds `[{tagName}]`):

```json
"tokenTag": {
  "Social Events": [{"tagName": "DEX Paid"}],
  "Launch Platform": [{"tagName": "Pumpfun"}],
  "Sensitive Events": [{"tagName": "Smart Money Add Holdings"}],
  "Wash Trading Behavior": [{"tagName": "Insider Wash Trading"}]
}
```

**Signal quality:** `smartMoneyCount ≥ 5` = stronger conviction · `exitRate ≥ 70` = already exiting, treat with caution · `status:"timeout"` = no longer actionable.

---

## 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 (check `chainId`/`pageSize`) · `000400` unsupported chain.

#!/usr/bin/env node
// trading-signal CLI — self-contained, zero-dep, Node >= 22
// Usage: node cli.mjs <command> '<json_params>'
//
// Commands:
//   smart-money  POST  on-chain Smart Money trading signals (BSC + Solana)

// ---- inline HTTP helper (self-contained, zero dependency) ----
const TIMEOUT_MS = 10_000;
const UA = { 'Accept-Encoding': 'identity', 'User-Agent': 'binance-web3/2.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 = {
  'smart-money': new Set(['56', 'CT_501']),
};

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 = {
  'smart-money': (p) => {
    validateChainId('smart-money', p.chainId);
    return {
      url: 'https://web3.binance.com/bapi/defi/v1/public/wallet-direct/buw/wallet/web/signal/smart-money/ai',
      method: 'POST',
      body: 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);
  }
}

---
name: trading-signal
description: |
  Per-trade smart-money signals — each result is a discrete buy or sell event from a tracked smart-money wallet,
  with trigger price, current price, max gain since trigger, and exit rate. BSC and Solana only.
  Use for: "smart money buy signal on $X", "any whale just bought $Y", "alpha signals in the last hour",
  "copy-trade-worthy signals", "trigger price and max gain on these trades", "on-chain trading signals from smart money".
metadata:
  author: binance-web3-team
  version: "2.0"
---

# Trading Signal Skill

## Overview

This skill retrieves on-chain Smart Money trading signals to help users track professional investors:

Get smart money buy/sell signals
Compare signal trigger price with current price
Analyze max gain and exit rate of signals
Get token tags (e.g., Pumpfun, DEX Paid)


## When to Use This Skill

| User intent | Command |
|-------------|---------|
| Get on-chain smart-money buy/sell signals with gain + exit-rate data | `smart-money` |

## Supported Chains

| Chain | chainId |
|-------|---------|
| BSC | `56` |
| Solana | `CT_501` |

## How to Call APIs

```bash
node <skill-dir>/scripts/cli.mjs smart-money '{"chainId":"CT_501","page":1,"pageSize":50}'
```

## Commands

| Command | Purpose | Required args | Example |
|---------|---------|---------------|---------|
| `smart-money` | Smart-money buy/sell signals with trigger price, max gain, exit rate | `chainId` | `node <skill-dir>/scripts/cli.mjs smart-money '{"chainId":"56","page":1,"pageSize":50}'` |

Optional args: `page` (default 1), `pageSize` (**max 100**), `smartSignalType` (filter; empty string = all).

## Rules

- **`pageSize` cap is 100** — larger values are silently clamped upstream.
- **`status` enum** (map to user-friendly language when summarizing):
  - `active` — signal still valid
  - `timeout` — exceeded observation window (may still be informative, but stale)
  - `completed` — reached target / stop loss
  Prefer `active` signals when surfacing actionable opportunities.
- **Quality indicators**: higher `smartMoneyCount` (more distinct smart-money addresses) implies higher signal reliability; high `exitRate` (%) suggests smart money has already exited, so the opportunity may have passed.
- **`direction`** is `buy` or `sell` — always include this when summarizing a signal.
- **Icon URL prefix**: `logoUrl` is a relative path; prepend `https://bin.bnbstatic.com`. `chainLogoUrl` is already a full URL. Timestamps are ms; `maxGain` is a % string — convert before arithmetic.

## Full CLI Reference

See [`references/cli.md`](references/cli.md) for per-subcommand invocations, parameter tables, signal / tag / performance field tables, and real response samples.