Skill: numpy0001/okx-cex-smartmoney (version 1.3.5)

--- name: okx-cex-smartmoney description: "Smart Money analytics on OKX: leaderboard traders, position tracking, trade records, closed-position history, aggregated consensus signals, and signal history. Use this skill when the user asks about 聪明钱, smart money, 牛人榜, leaderboard, top traders, 交易员排行, trader ranking, trader positions, trader PnL, 交易员持仓, 交易员收益, 历史平仓, closed positions, realized PnL track record, trade history, 成交记录, smart money signal, 聪明钱信号, long/short ratio, 多空比, capital flow, 资金流向, position conviction, 仓位强度, entry price distribution, smart money overview, 聪明钱总览, signal history, 信号历史, trader search, 搜索交易员, who is trading BTC, 谁在交易BTC, recommend traders, 推荐交易员, best traders, top performers." license: MIT metadata: author: okx version: "1.3.5" homepage: "https://www.okx.com" agent: requires: bins: ["okx"] install: - id: npm kind: node package: "@okx_ai/okx-trade-cli@1.3.3" bins: ["okx"] label: "Install okx CLI (npm)" --- # OKX CEX Smart Money CLI Smart Money leaderboard, trader analytics, position tracking, and aggregated consensus signals. ## Preflight Before running any command, follow [`../_shared/preflight.md`](../_shared/preflight.md). Use `metadata.version` from this file's frontmatter as the reference for Step 2. ## Prerequisites 1. Install `okx` CLI: ```bash npm install -g @okx_ai/okx-trade-cli ``` 2. Configure credentials: ```bash okx config init # select site -> follow browser OAuth flow ``` 3. Verify: `okx smartmoney traders-by-filter --limit 5` > **Security**: NEVER accept credentials in chat. Guide users to `okx config init` for setup. --- ## Credential & Profile Check Run **both** commands before any authenticated command — the `apiKey` field from `okx auth status --json` is the auth-binary's internal state and is always `false` regardless of whether `~/.okx/config.toml` has an API-key profile. `okx config show --json` is the only authoritative source for API-key presence. The auth method is detected during [preflight](../_shared/preflight.md) Step 2 and remembered for the session. ```bash okx config show --json # reveals API-key profiles (TOML config) okx auth status --json # reveals OAuth session state (auth-binary state) ``` Apply **in this order** — first match wins: - `config show --json` has any profile with a non-empty `api_key` field → **API Key mode**. Proceed. - No API-key profile **AND** `auth status --json` returns `"status":"logged_in"` → **OAuth mode**. Proceed. - No API-key profile **AND** `"status":"pending"` — login is in progress, wait for it to complete. - No API-key profile **AND** `"status":"not_logged_in"` — **stop**, load `okx-cex-auth` skill and follow login steps, wait for completion. Smart Money does not support demo mode (leaderboard data is live-only). Always use live mode silently — don't mention it unless there's an error. - **API Key users**: use `--profile <live-profile>` (the profile without `demo=true`). - **OAuth users**: no flag needed (live is the default). **On authentication errors (401 / "Session expired" / "Run `okx auth login` first"):** stop immediately, load `okx-cex-auth` skill and follow re-authentication steps, then retry. --- ## Skill Routing | User intent | Route to skill | |---|---| | Market prices, tickers, candles | `okx-cex-market` | | Spot / swap / futures / options orders | `okx-cex-trade` | | Account balance, positions, transfers | `okx-cex-portfolio` | | Grid / DCA trading bots | `okx-cex-bot` | | Simple Earn, Flash Earn, On-chain Earn, Dual Investment (双币赢), or AutoEarn (自动赚币) | `okx-cex-earn` | | Smart Money leaderboard, signals, trader analytics | **This skill** | --- ## Command Index (10 commands, all read-only) ### Trader family (6) | Command | Type | Auth | Description | |---|---|---|---| | `smartmoney traders-by-filter` | READ | Required | Leaderboard ranking by pool conditions (period / minPnl / minWinRate / maxDrawdown / minAum). Paginated by `authorId`. Names use `min*` / `max*` prefix — disjoint from signal-side `*Tier` namespace. | | `smartmoney performance-by-trader --authorIds <id1,id2>` | READ | Required | PnL / win-rate profile for one or more authorIds. `--sortBy <pnl\|pnlRatio>` (default `pnl`) and `--period <3\|7\|30\|90>` (default `90`) drive ranking and lookback window. | | `smartmoney search-trader --keyword <name>` | READ | Required | Search Top Traders by nickname keyword (≤10 results, ranked by follower count). | | `smartmoney trader-positions --authorId <id>` | READ | Required | Current open positions for one trader. Filter by `--instId <BTC-USDT-SWAP>` (or bare base ccy). | | `smartmoney trader-positions-history --authorId <id>` | READ | Required | Closed-position history with realized PnL. Paginated by `posId`. | | `smartmoney trader-orders-history --authorId <id>` | READ | Required | Order / fill records. Paginated by `ordId`. | ### Signal / coin family (4) | Command | Type | Auth | Description | |---|---|---|---| | `smartmoney signal-overview-by-filter` | READ | Required | Multi-asset signal, tier-filtered pool. Pick coins via `--topInstruments` (top-N hottest) OR `--instCcyList BTC,ETH,SOL` (specific) — exactly one. Use this to discover the hottest coins among smart money. | | `smartmoney signal-overview-by-trader --authorIds <id1,id2>` | READ | Required | Multi-asset signal aggregated over a hand-picked set of traders (authorIds-direct-lookup). Pick coins via `--topInstruments` OR `--instCcyList`. `--sortBy` (default `pnl`) and `--period` (default `7`) drive capability metrics. Capability tier filters (pnlTier / winRateTier / etc.) not exposed. | | `smartmoney signal-trend-by-filter --instCcy <ccy> [--asOfTime <yyyyMMddHH>]` | READ | Required | Single-coin smart-money signal time-series anchored at `asOfTime` (defaults to current UTC hour), tier-filtered pool. `--granularity 1h\|1d`, `--limit` controls bucket count. | | `smartmoney signal-trend-by-trader --authorIds <id1,id2> --instCcy <ccy> [--asOfTime <yyyyMMddHH>]` | READ | Required | Single-coin smart-money signal time-series aggregated over a hand-picked set of traders (authorIds-direct-lookup). `--granularity 1h\|1d` (default `1h`), `--sortBy` (default `pnl`), `--period` (default `7`). Capability tier filters not exposed. | > **Time anchor**: `signal-trend-by-{filter,trader}` take an optional `--asOfTime <yyyyMMddHH>` (10-digit UTC hour, e.g. `2026050100`). Returns the latest `--limit` buckets ending at that anchor. Omit `--asOfTime` to use the current UTC hour. `signal-overview-by-{filter,trader}` does not expose any time input — handler always uses the current hour. > **Multi-coin selection**: `signal-overview-by-filter` and `signal-overview-by-trader` accept `--topInstruments` (top-N hottest) **or** `--instCcyList BTC,ETH,SOL` (explicit base ccy list). The two flags are mutually exclusive. Passing neither defaults to `--topInstruments=20`. > **⚠ Linear-only scope**: All four `signal-*` commands aggregate **USDT-margined and USDS-margined contracts only**. Coin-margined contracts (`BTC-USD-SWAP`, `BTC-USD-DELIVERY`, `ETH-USD-SWAP`, …) are excluded by upstream — a trader's coin-margined positions are silently dropped from `longNotional` / `shortNotional` / `tradersWithPosition`. If a trader holds large coin-margined exposure but no linear position on that coin, they will not appear in the signal at all. To see a trader's full position book including coin-margined, run `smartmoney trader-positions --authorId <id>`. > **Need a trader's full picture?** The old `smartmoney trader` composite command is removed. Run `performance-by-trader`, `trader-positions`, and `trader-orders-history` in parallel. For full command syntax and parameters, read `{baseDir}/references/trader-commands.md` and `{baseDir}/references/signal-commands.md`. --- ## Operation Flow ### Step 0 — Credential & Profile Check Before any authenticated command: see [Credential & Profile Check](#credential--profile-check). Always use live mode silently. ### Step 1 — Identify intent **Trader discovery / ranking:** - "推荐交易员" / "top traders" / "牛人榜" → `smartmoney traders-by-filter` with sorting/filtering. See `{baseDir}/references/trader-commands.md`. - "看看某个交易员" / "trader detail" → run `performance-by-trader`, `trader-positions`, `trader-orders-history` **in parallel** (the old composite `smartmoney trader` is removed). - "搜索 alice / 小明" / "find trader by nickname" → `smartmoney search-trader --keyword <name>` (returns ≤10 matches with `authorId` to feed into other tools). - "verify these authorIds" / 已知 authorId → `smartmoney performance-by-trader --authorIds <id1,id2>` (direct lookup; `--sortBy` / `--period` honored, defaults `pnl` / `90`). - "他的当前持仓" / "current positions only" → `smartmoney trader-positions --authorId <id>`. - "他的成交记录" / "trade history" → `smartmoney trader-orders-history --authorId <id>` (paginated). - "历史平仓" / "closed positions" / "realized PnL track record" → `smartmoney trader-positions-history --authorId <id>` (paginated). **Signal analysis:** - "BTC 聪明钱信号" / "smart money signal for BTC" → `smartmoney signal-overview-by-filter --instCcyList BTC`. See `{baseDir}/references/signal-commands.md`. - "BTC ETH SOL 这几个币的信号" / "signals for these specific coins" → `smartmoney signal-overview-by-filter --instCcyList BTC,ETH,SOL`. - "这几个交易员看哪些币？" / "consensus among these specific traders" → `smartmoney signal-overview-by-trader --authorIds <id1,id2>` (defaults to top-20 hottest among the group, or pass `--instCcyList`). - "聪明钱关注哪些币？" / "what are smart money trading right now?" → `smartmoney signal-overview-by-filter` (defaults to `--topInstruments=20`). See `{baseDir}/references/signal-commands.md`. - "信号趋势" / "signal trend over time" → `smartmoney signal-trend-by-filter --instCcy <ccy> [--asOfTime <yyyyMMddHH>] [--limit 24]` (or `signal-trend-by-trader --authorIds <ids> --instCcy <ccy>` for an authorIds-scoped trend). ### Step 2 — Execute and present All commands are READ-only — no confirmation needed. Always pass `--json` and render results as Markdown tables. For multi-step workflows (recommend traders then drill down, signal analysis with context), read `{baseDir}/references/workflows.md`. --- ## Global Notes - **Security:** Never ask users to paste API keys or secrets into chat. - **Output:** Always pass `--json` to list/query commands and render results as a Markdown table — never paste raw terminal output. - **Network errors:** If commands fail with a connection error, prompt user to check VPN: `curl -I https://www.okx.com` - **Language:** Always respond in the user's language. - **Time inputs:** `signal-trend-by-{filter,trader}` take an optional `--asOfTime <yyyyMMddHH>` anchor (10-digit UTC hour); omit to use the current UTC hour. `--limit` controls how many buckets are returned ending at that anchor. `signal-overview-by-{filter,trader}` takes no time input — handler always uses the current hour. For number/time formatting and response structure conventions, read `{baseDir}/references/templates.md`.

path: references/workflows.md
content: # Smart Money Workflows

## 1. Recommend Top Traders

> User: "推荐聪明钱" / "top performers this month"

```bash
okx --profile live smartmoney traders-by-filter --period 30 --sortBy pnl --limit 10 --json
```

Present as Markdown table with: rank, nickName, pnl, pnlRatio, winRate, asset.

Highlight:
- Highest absolute PnL
- Best return ratio (pnlRatio)
- Best risk-adjusted (high winRate + low maxDrawdown)

---

## 2. Drill Down into a Trader (no composite — fan out in parallel)

> User: "看看这个交易员的详情" / "show me trader X"

The old `smartmoney trader` composite command was removed. Run all three atomic commands in parallel:

```bash
# Run in parallel — three independent endpoints
okx --profile live smartmoney performance-by-trader --authorIds <id> --json
okx --profile live smartmoney trader-positions --authorId <id> --json
okx --profile live smartmoney trader-orders-history --authorId <id> --limit 50 --json
```

Present in three sections: profile summary (from `performance-by-trader`), then current positions table (from `trader-positions`), then recent orders table (from `trader-orders-history`).

For closed-position history (realized PnL trail), add a fourth call:

```bash
okx --profile live smartmoney trader-positions-history --authorId <id> --limit 50 --json
```

`trader-orders-history` and `trader-positions-history` return top-level `pagination: { hasMore, nextAfter }` — pass `nextAfter` as `--after` for the next page.

---

## 3. Verify / Look Up Specific Traders

> User: "show me stats for these authorIds" / "verify trader 1001,1002"

```bash
okx --profile live smartmoney performance-by-trader --authorIds <id1>,<id2>,<id3> --json
```

If the user provides a **nickName** (e.g. "alice", "小明") instead of an authorId, resolve it first via `search-trader` and then feed the resulting authorId(s) into the other tools:

```bash
# Step 1: resolve nickname → up to 10 candidate Top Traders
okx --profile live smartmoney search-trader --keyword alice --json

# Step 2: take the chosen authorId from the result and look up performance / positions etc.
okx --profile live smartmoney performance-by-trader --authorIds <authorId> --json
```

> `search-trader` returns at most 10 matches sorted by OKX-platform follower count DESC, restricted to the Top Trader set. An empty array means no profitable leaderboard trader matched the keyword.

---

## 4. Filter Traders by Criteria

> User: "找胜率80%以上的交易员" / "traders with > 80% win rate"

```bash
okx --profile live smartmoney traders-by-filter --minWinRate 0.8 --period 30 --sortBy pnl --limit 10 --json
```

> User: "回撤低于10%的" / "max drawdown under 10%"

```bash
okx --profile live smartmoney traders-by-filter --maxDrawdown 0.1 --period 30 --limit 10 --json
```

> Note: leaderboard uses **numeric thresholds** with `min*` / `max*` prefix (`--minPnl 10000`, `--minWinRate 0.8`, `--maxDrawdown 0.1`, `--minAum 1000`). Signal-side endpoints use **enum tiers** with `*Tier` suffix (`--pnlTier PNL_TOP20`, `--winRateTier WR_GE_80`, `--maxDrawdownTier MR_LE_20`, `--aumTier AUM_TOP20`). The two surfaces have disjoint flag names by design — passing leaderboard names to signal endpoints (or vice versa) silently no-ops.

---

## 5. Smart Money Signal for a Coin

> User: "BTC 聪明钱信号" / "smart money consensus on ETH"

```bash
# No --ts needed — handler auto-uses current hour
okx --profile live smartmoney signal-overview-by-filter --instCcyList BTC --json
```

Present signal summary (each `data[]` item has outer fields + 3 nested groups: `notional`, `longShortRatio`, `winRate`):
- Outer: `ccy`, `dataVersion`, `tradersWithPosition`, `tradersQualified`, `longTraders`, `shortTraders`
- Long/short ratio (under `longShortRatio`): `longRatio`, `shortRatio`, `weightedLongRatio`, `weightedShortRatio`
- Trend deltas (under `longShortRatio`): `longRatioVs1h`, `longRatioVs24h`, `longRatioVs7d`
- Capital (under `notional`): `longNotionalUsdt`, `shortNotionalUsdt`, `netNotionalUsdt`, `totalNotionalUsdt`, `totalNotionalVs24h`
- Entry prices (under `notional`): `smartMoneyLongAvgEntry`, `smartMoneyShortAvgEntry`
- Win rates (under `winRate`): `avgLongWinRate`, `avgShortWinRate`

> **Notional pricing**: All `notional.*` fields and `weightedLongRatio` / `weightedShortRatio` are weighted by each trader's **entry price (`price_avg`)**, NOT mark price. They move only when positions are scaled (open / close / add) and stay constant across hourly buckets when traders hold positions unchanged. For real-time price comparison, compare `notional.smartMoneyLongAvgEntry` / `smartMoneyShortAvgEntry` against `okx market ticker` in parallel.

> Older fields `currentPrice` / `priceChange24h` / `fundingRate` / `openInterest` / `longShortAccountRatio` are no longer returned. For real-time market context, fan out to `okx market ticker` in parallel.

---

## 6. Top-N Most-Watched Coins (and multi-coin consensus)

> User: "聪明钱关注哪些币？" / "what are smart money trading right now?" / "BTC ETH SOL 这几个币的共识"

```bash
# Top-N hottest among smart money (default 20)
okx --profile live smartmoney signal-overview-by-filter --topInstruments 20 --json

# Or: specific coin list
okx --profile live smartmoney signal-overview-by-filter --instCcyList BTC,ETH,SOL --json
```

`signal-overview-by-filter` accepts `--topInstruments` OR `--instCcyList` (mutually exclusive). Default is `--topInstruments=20` when neither is given. Snapshot is always the **current hour** — no `--ts` / `--dataVersion`. For a historical comparison call `signal-trend-by-filter` per instrument with the desired `--asOfTime` anchor and `--limit` bucket count.

> **⚠ Linear-only scope**: Aggregations include USDT-margined and USDS-margined instruments only (e.g. `BTC` covers `BTC-USDT-SWAP` + `BTC-USDS-SWAP`). Coin-margined contracts (`BTC-USD-SWAP`, `BTC-USD-DELIVERY`, …) are excluded — a trader's coin-margined exposure is silently dropped from the signal, which can materially understate institutional / coin-margined whales on majors like BTC and ETH. If the user asks why a trader with a known large BTC position does not show up under `--instCcyList BTC`, suspect coin-margined and verify with `trader-positions`.

Table columns to surface: `ccy`, `tradersWithPosition`, `longShortRatio.longRatio`, `longShortRatio.weightedLongRatio`, `notional.netNotionalUsdt`, `longShortRatio.longRatioVs1h` / `longRatioVs24h` / `longRatioVs7d`, `notional.smartMoneyLongAvgEntry`, `notional.smartMoneyShortAvgEntry`, `notional.totalNotionalVs24h`.

---

## 7. Signal Trend Analysis (single coin over time)

> User: "BTC 信号趋势" / "how has the BTC signal changed?"

```bash
# 30 daily buckets ending at the current UTC hour, scoped to BTC
okx --profile live smartmoney signal-trend-by-filter --instCcy BTC --granularity 1d --limit 30 --json

# Or anchor at a specific UTC hour (10-digit yyyyMMddHH)
okx --profile live smartmoney signal-trend-by-filter --instCcy BTC --asOfTime 2026050100 --granularity 1d --limit 30 --json
```

Present as time-series table: dataVersion, ccy, longRatio, shortRatio, weightedLongRatio, weightedShortRatio, longTraders, shortTraders, tradersWithPosition, tradersQualified, netNotionalUsdt, totalNotionalUsdt.

> **Reading the trend**: `weightedLongRatio` / `weightedShortRatio` / `netNotionalUsdt` / `totalNotionalUsdt` are entry-price-weighted (`price_avg`), not mark-price-weighted. A flat trend across buckets means traders held positions unchanged — it does NOT mean underlying price was flat. To detect actual scaling, watch for changes in these values; to gauge price movement, fetch `okx market candles` separately.

For an authorIds-scoped trend (consensus of a hand-picked set of traders; capability tier filters not exposed — `_by_trader` is direct-lookup, backend uses tier defaults; `--sortBy` and `--period` are accepted):

```bash
okx --profile live smartmoney signal-trend-by-trader --authorIds <id1>,<id2> --instCcy BTC --granularity 1d --limit 30 --sortBy pnl --period 7 --json
```

---

## 8. Cross-Skill: Smart Money + Market Context

> User: "聪明钱看多BTC吗？" / "are smart money traders bullish on BTC?"

```bash
# Run in parallel:

# 1. Smart money signal (current hour, auto-filled)
okx --profile live smartmoney signal-overview-by-filter --instCcyList BTC --json

# 2. Current market price (via okx-cex-market skill)
okx --profile live market ticker BTC-USDT-SWAP --json
```

Combine: compare `notional.smartMoneyLongAvgEntry` / `notional.smartMoneyShortAvgEntry` vs current price; interpret `longShortRatio.longRatio` + `longShortRatio.longRatioVs24h` / `longRatioVs7d` deltas.

---

## 9. Recommend and Deep Dive

> User: "推荐一个交易员给我看看" / "recommend a trader and show details"

```bash
# Step 1: Get top traders
okx --profile live smartmoney traders-by-filter --period 30 --sortBy pnl --limit 5 --json

# Step 2: Pick best candidate, fan out the three atomic commands in parallel
okx --profile live smartmoney performance-by-trader --authorIds <top_trader_id> --json
okx --profile live smartmoney trader-positions --authorId <top_trader_id> --json
okx --profile live smartmoney trader-orders-history --authorId <top_trader_id> --limit 50 --json
```

---

## 10. Audit a Trader's Realized PnL Pattern

> User: "这个交易员历史平仓的胜率/盈亏曲线" / "show this trader's closed-position track record"

```bash
# Page 1: most recent 50 closed positions
okx --profile live smartmoney trader-positions-history --authorId <id> --limit 50 --json

# If pagination.hasMore=true, page 2 uses pagination.nextAfter as --after:
okx --profile live smartmoney trader-positions-history --authorId <id> --limit 50 --after <posId> --json
```

Aggregate over `realizedPnl` / `pnlRatio` / `closeType` to characterize the trader (e.g. "8/10 winning closes, 1 liquidation, median ratio +12%"). Useful for risk assessment beyond the snapshot stats in `traders-by-filter`.

---

## 11. Trade History for One Symbol

> User: "trader X 的 BTC 成交记录"

```bash
okx --profile live smartmoney trader-orders-history --authorId <id> --instId BTC-USDT-SWAP --limit 50 --json
```

Present as time-ordered table: `cTime`, `instId`, `side`, `posSide`, `ordType`, `avgPx`, `sz`, `value`. For deeper history, paginate via `pagination.nextAfter` (last `ordId`).


path: references/templates.md
content: # Templates & Formatting Reference

## Trader Ranking Table Template

| # | Trader | 30d PnL | Return | Win Rate | Max DD | Asset |
|---|--------|---------|--------|----------|--------|-------|
| 1 | {nickName} | ${pnl} | {pnlRatio}% | {winRate}% | {maxDrawdown}% | ${asset} |

## Trader Profile Template

```
=== {nickName} ===
Author ID:    {authorId}
PnL:          ${pnl} ({pnlRatio}%)
Win Rate:     {winRate}%
Max Drawdown: {maxDrawdown}%
Total Asset:  ${asset}
Onboard Days: {onboardDuration}
```

## Position Table Template

| Instrument | Side | Leverage | Entry Price | Current Price | Notional (USD) | PnL |
|------------|------|----------|-------------|---------------|----------------|-----|
| {instId} | {posSide} | {lever}x | {avgPx} | {last} | ${notionalUsd} | {pnl} |

## Trade Record Table Template

| Instrument | Side | Position | Type | Leverage | Price | Avg Fill | Size | Value | Time |
|------------|------|----------|------|----------|-------|----------|------|-------|------|
| {instId} | {side} | {posSide} | {ordType} | {lever}x | {px} | {avgPx} | {sz} | {value} | {cTime} |

## Formatting Reference

- **Numbers:** Full precision with currency unit (e.g. `$519,100.54`)
- **Ratios:** Display as percentage (e.g. `0.8` → `80%`)
- **PnL Ratios:** Display as percentage with sign (e.g. `0.4699` → `+46.99%`)
- **Timestamps:** Unix ms → convert to user timezone, format: `YYYY/M/D HH:MM`
- **Response structure:** Conclusion → Evidence → Recommended action
- **Rate limits:** 5 requests per endpoint per second


path: references/signal-commands.md
content: # Signal Commands Reference

> Signal endpoints are under `/api/v5/journal/smartmoney/`.

Four atomic commands cover the signal / coin side, split by **entry mode**:

- **`signal-overview-by-filter`** — multi-asset, **tier-discovery scenario**: full pool-filter knobs exposed (sortBy / pnlTier / winRateTier / maxDrawdownTier / aumTier / lmtNum). Use this for "most-watched-by-smart-money instruments" by passing `--topInstruments`.
- **`signal-overview-by-trader`** — multi-asset, **authorIds-direct-lookup scenario**: `--authorIds` + coin selection + `--sortBy` / `--period` (drive capability metrics). Capability tier filters (pnlTier / winRateTier / etc.) not exposed.
- **`signal-trend-by-filter`** — single coin time-series anchored at `asOfTime` (default = current UTC hour), tier-discovery scenario (full pool filters exposed).
- **`signal-trend-by-trader`** — single coin time-series anchored at `asOfTime`, authorIds-direct-lookup scenario. `--sortBy` / `--period` exposed; capability tier filters not exposed.

The previous overloaded `smartmoney signal` command (which switched on `--authorIds` presence), `smartmoney overview` (which switched on `--instCcyList`), and the narrow `top-coin-signals` shortcut are all removed. To get the top-N most-watched coins, call `signal-overview-by-filter` (defaults to `--topInstruments=20`).

---

## smartmoney signal-overview-by-filter — Multi-Asset Signal (pool filter mode)

```bash
okx smartmoney signal-overview-by-filter [--topInstruments <n> | --instCcyList <BTC,ETH,...>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n>] [--json]
```

Aggregates pool traders' positions across multiple instruments to produce per-instrument long/short ratio, weighted ratio, avg entry price, capital flow, and trend deltas vs 1h/24h/7d.

Pick instruments via `--topInstruments` (top-N hottest) **OR** `--instCcyList` (specific coins) — exactly one. If both are passed the handler errors. If neither is passed it defaults to `--topInstruments=20`.

| Param | Required | Default | Description |
|---|---|---|---|
| `--topInstruments` | No | `20` | Top-N hottest instruments (1–100). Mutually exclusive with `--instCcyList`. |
| `--instCcyList` | No | - | Comma-separated base ccys, e.g. `BTC,ETH,SOL`. Mutually exclusive with `--topInstruments`. **Linear-only**: matches USDT-margined and USDS-margined instruments only (e.g. `BTC` covers `BTC-USDT-SWAP` + `BTC-USDS-SWAP`). Coin-margined `BTC-USD-SWAP` / `BTC-USD-DELIVERY` positions are excluded by upstream. |
| `--lmtNum` | No | `100` | Upper bound on `tradersQualified` (final aggregation pool size). Candidates pass through tier filters, then truncated to top-N by `sortBy` (DESC). `tradersQualified` ≤ `lmtNum` always. Range 1–2000; values above ~1500 add latency without benefit. |

> **No `--ts` parameter.** The handler always uses the current hour. For historical timeline, use `signal-trend-by-filter`.

> **⚠ Coin-margined excluded.** A trader's coin-margined positions on the requested base ccy are silently dropped from `longNotional` / `shortNotional` / `tradersWithPosition`. If a trader holds only coin-margined exposure on a coin, they will not appear in the signal. Use `smartmoney trader-positions --authorId <id>` to inspect the full book.

> The old `--instId`, `--instCcy`, and `--dataVersion` flags are removed.

Pool filter params (see [Signal Filter Enums](#signal-filter-enum-values) below) apply.

### Response Fields (per instrument, array `data[]`)

Each item has an outer ID + 3 nested groups (`notional`, `longShortRatio`, `winRate`).

**Outer fields**

| Field | Type | Description |
|---|---|---|
| `ccy` | String | Instrument ID e.g. `BTC-USDT-SWAP` (outer key is `ccy`, NOT `instId`) |
| `dataVersion` | String | UTC `yyyyMMddHH` — 10 digits, hour-floored (e.g. `2026043014`) |
| `tradersWithPosition` | Integer | Pool traders holding this asset (long+short, double-sided counted once) |
| `tradersQualified` | Integer | Final aggregation pool size after tier filters + top-N truncation by `sortBy`. Always ≤ `lmtNum`. Smaller than `lmtNum` only when candidate pool underflows (rare ccy / strict tier combos). |
| `longTraders` | Integer | Pool traders currently long this asset |
| `shortTraders` | Integer | Pool traders currently short this asset |

**`notional` group** (capital flow)

| Field | Type | Description |
|---|---|---|
| `longNotionalUsdt` | String | Total long notional (USDT) |
| `shortNotionalUsdt` | String | Total short notional (USDT) |
| `netNotionalUsdt` | String | Net = long − short, can be negative |
| `totalNotionalUsdt` | String | Gross = long + short |
| `totalNotionalVs24h` | String | (curr − hist_24h)/hist_24h; positive = adding, negative = retreating; NULL when hist=0 |
| `smartMoneyLongAvgEntry` | String | Weighted avg entry across long positions (NULL when no long) |
| `smartMoneyShortAvgEntry` | String | Weighted avg entry across short positions (NULL when no short) |

**`longShortRatio` group** (ratio + historical deltas)

| Field | Type | Description |
|---|---|---|
| `longRatio` | String | `longTraders / tradersWithPosition`, decimal [0, 1] |
| `shortRatio` | String | `shortTraders / tradersWithPosition` |
| `weightedLongRatio` | String | `Σ(long_notional) / Σ(notional)` |
| `weightedShortRatio` | String | `Σ(short_notional) / Σ(notional)` |
| `longRatioVs1h` | String | `longRatio − hist_1h.longRatio`; NULL when no hist |
| `longRatioVs24h` | String | `longRatio − hist_24h.longRatio`; NULL when no hist |
| `longRatioVs7d` | String | `longRatio − hist_7d.longRatio`; NULL when no hist |

**`winRate` group** (capability — driven by `period`)

| Field | Type | Description |
|---|---|---|
| `avgLongWinRate` | String | Mean closed-position win-rate over `period` days for users currently long; NULL when sample below threshold |
| `avgShortWinRate` | String | Same for users currently short; NULL when sample below threshold |

> **Notional pricing**: `longNotionalUsdt` / `shortNotionalUsdt` / `netNotionalUsdt` / `totalNotionalUsdt` and `weightedLongRatio` / `weightedShortRatio` are weighted by each trader's **entry price (`price_avg`)**, NOT mark price. Values move only when positions are scaled (open / close / add) — they stay constant across buckets when traders hold positions unchanged.

> **Note**: `signal-history` (used by `signal-trend-*`) still returns `dataVersion` in `yyyyMMddHH` format (10 digits) — same as overview.

---

## smartmoney signal-overview-by-trader — Multi-Asset Signal (authorIds-direct-lookup)

```bash
okx smartmoney signal-overview-by-trader --authorIds <id1>,<id2> [--topInstruments <n> | --instCcyList <BTC,ETH,...>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--json]
```

Aggregates signals over a hand-picked set of traders. Use this when the caller already has a list of authorIds (e.g. discovered via `traders-by-filter` or `search-trader`) and wants their consensus on multiple coins. Useful for "what do my watchlist of traders think across coins?".

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorIds` | Yes | - | Comma-separated trader IDs (e.g. `1001,1002,1003`) |
| `--topInstruments` | No | `20` | Top-N hottest instruments held by the group. Mutually exclusive with `--instCcyList`. |
| `--instCcyList` | No | - | Comma-separated base ccys. Mutually exclusive with `--topInstruments`. **Linear-only** — coin-margined (`-USD-SWAP` / `-USD-DELIVERY`) positions held by the trader set are NOT included; cross-check with `trader-positions` if a trader's known coin-margined exposure is missing. |
| `--sortBy` | Yes | `pnl` | Ranking key for the trader set: `pnl` or `pnlRatio` |
| `--period` | Yes | `7` | Lookback window in days for capability metrics (`winRate.avgLongWinRate` / `avgShortWinRate`). Pass `3` / `7` / `30` / `90`. |

> **Capability tier filters not exposed** — `_by_trader` is the authorIds-direct-lookup scenario; tier filters (`pnlTier` / `winRateTier` / `maxDrawdownTier` / `aumTier`) and `lmtNum` use backend defaults. If you need tier-driven filtering instead, use `signal-overview-by-filter`.

> No `--ts` parameter. Handler uses the current hour.

Response fields: same as `signal-overview-by-filter`.

---

## smartmoney signal-trend-by-filter — Single-Asset Time-Series (pool filter)

```bash
okx smartmoney signal-trend-by-filter --instCcy <ccy> [--asOfTime <yyyyMMddHH>] [--granularity <1h|1d>] [--limit <n>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--pnlTier <tier>] [--winRateTier <tier>] [--maxDrawdownTier <tier>] [--aumTier <tier>] [--lmtNum <n>] [--json]
```

Historical single-coin signal snapshots across hourly/daily buckets, anchored at `asOfTime`. Returns the latest `--limit` buckets ending at the anchor (newest first). Omit `--asOfTime` to use the current UTC hour.

| Param | Required | Default | Description |
|---|---|---|---|
| `--instCcy` | Yes | - | Base currency to scope the time-series, e.g. `BTC`. **Linear-only** (USDT/USDS-margined); coin-margined contracts excluded. |
| `--asOfTime` | No | (current UTC hour) | 10-digit UTC anchor `yyyyMMddHH` (e.g. `2026050100`) |
| `--granularity` | No | `1h` | Bucket size: `1h` or `1d` |
| `--limit` | No | `24` | Number of buckets (1–500) ending at `asOfTime` |
| `--lmtNum` | No | `100` | Upper bound on `tradersQualified` per bucket. Candidates pass through tier filters, then truncated to top-N by `sortBy` (DESC). `tradersQualified` ≤ `lmtNum` always; equals `lmtNum` unless candidate pool underflows (rare ccy / strict tier combos). Range 1–2000; values above ~1500 add latency without benefit (exceeds typical candidate pool size). |

Pool filter params (see [Signal Filter Enums](#signal-filter-enum-values) below) apply.

### Response Fields (per time bucket, array `data[]` sorted by time DESC)

| Field | Type | Description |
|---|---|---|
| `ccy` | String | Base currency / instrument key |
| `dataVersion` | String | UTC `yyyyMMddHH` (10 digits, e.g. `2026042820`) |
| `longRatio` | String | Long ratio at this bucket = `longTraders / tradersWithPosition` |
| `shortRatio` | String | Short ratio at this bucket = `shortTraders / tradersWithPosition` |
| `weightedLongRatio` | String | Notional-weighted long ratio = `Σ(long_notional) / Σ(notional)` |
| `weightedShortRatio` | String | Notional-weighted short ratio = `Σ(short_notional) / Σ(notional)` |
| `longTraders` | Integer | Traders with long exposure (includes dual-side) |
| `shortTraders` | Integer | Traders with short exposure (includes dual-side) |
| `tradersWithPosition` | Integer | Traders holding a position in this bucket |
| `tradersQualified` | Integer | Final aggregation pool size in this bucket after tier filters + top-N truncation by `sortBy`. Always ≤ `lmtNum`. |
| `netNotionalUsdt` | String | Net = long − short (USDT) |
| `totalNotionalUsdt` | String | Total = long + short (USDT) |

> **Notional pricing**: `weightedLongRatio` / `weightedShortRatio` / `netNotionalUsdt` / `totalNotionalUsdt` are weighted by each trader's **entry price (`price_avg`)**, NOT mark price. Values move only when positions are scaled (open / close / add) — they stay constant across buckets when traders hold positions unchanged.

---

## smartmoney signal-trend-by-trader — Single-Asset Time-Series (authorIds-direct-lookup)

```bash
okx smartmoney signal-trend-by-trader --authorIds <id1>,<id2> --instCcy <ccy> [--asOfTime <yyyyMMddHH>] [--granularity <1h|1d>] [--limit <n>] [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--json]
```

Time-series of a single coin's smart-money signal aggregated over a hand-picked set of traders. Useful for tracking how a specific group's consensus on one coin evolves over time.

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorIds` | Yes | - | Comma-separated trader IDs (e.g. `1001,1002,1003`) |
| `--instCcy` | Yes | - | Base currency to scope the time-series, e.g. `BTC`. **Linear-only** (USDT/USDS-margined); a trader's coin-margined positions on this base ccy are silently excluded. |
| `--asOfTime` | No | (current UTC hour) | 10-digit UTC anchor `yyyyMMddHH` |
| `--granularity` | No | `1h` | `1h` or `1d` |
| `--limit` | No | `24` | Bucket count (1–500) |
| `--sortBy` | Yes | `pnl` | Ranking key for the trader set: `pnl` or `pnlRatio` |
| `--period` | Yes | `7` | Lookback window in days. Pass `3` / `7` / `30` / `90`. Does NOT affect signal fields (always latest snapshot per bucket). |

> **Capability tier filters not exposed** — `_by_trader` is the authorIds-direct-lookup scenario; tier filters (`pnlTier` / `winRateTier` / `maxDrawdownTier` / `aumTier`) and `lmtNum` use backend defaults. If you need tier-driven filtering instead, use `signal-trend-by-filter`.

Response fields: same as `signal-trend-by-filter`.

---

## Signal Filter Enum Values

`--sortBy` and `--period` are accepted by **all four signal commands** (`_by_filter` and `_by_trader`). The capability tier flags below (`--pnlTier` / `--winRateTier` / `--maxDrawdownTier` / `--aumTier` / `--lmtNum`) are accepted **only by `_by_filter` siblings** — `_by_trader` siblings are authorIds-direct-lookup and these tier filters use backend defaults there.

| Param | Enum values | Default | Semantics |
|---|---|---|---|
| `--sortBy` | `pnl`, `pnlRatio` | `pnl` | Pool ranking key |
| `--period` | `3`, `7`, `30`, `90` | `7` | Lookback window in days for capability metrics |
| `--pnlTier` | `PNL_ANY`, `PNL_TOP50`, `PNL_TOP20`, `PNL_TOP5` | `PNL_ANY` | PnL percentile (top N% of pool) |
| `--winRateTier` | `WR_ANY`, `WR_GE_50`, `WR_GE_80` | `WR_ANY` | Career win-rate threshold (≥ N%, absolute) |
| `--maxDrawdownTier` | `MR_ANY`, `MR_LE_20`, `MR_LE_50` | `MR_ANY` | Max-drawdown threshold (≤ N%, absolute) |
| `--aumTier` | `AUM_ANY`, `AUM_TOP50`, `AUM_TOP20`, `AUM_TOP5` | `AUM_ANY` | AUM percentile (top N% of pool) |

> **Naming convention**: `TOP{N}` = percentile (top N% of pool — used by `pnlTier` / `aumTier` because their distributions are long-tailed); `GE_{N}` = absolute threshold ≥ N% (`winRateTier`); `LE_{N}` = absolute threshold ≤ N% (`maxDrawdownTier`). Don't read `WR_GE_80` as "top 80%" — it means win-rate ≥ 80%.

> All enums are case-insensitive; invalid values silently fall back to default.

---

## MCP Tool Reference

| CLI Command | MCP Tool |
|---|---|
| `smartmoney signal-overview-by-filter` | `smartmoney_get_signal_overview_by_filter` |
| `smartmoney signal-overview-by-trader` | `smartmoney_get_signal_overview_by_trader` |
| `smartmoney signal-trend-by-filter` | `smartmoney_get_signal_trend_by_filter` |
| `smartmoney signal-trend-by-trader` | `smartmoney_get_signal_trend_by_trader` |


path: references/trader-commands.md
content: # Trader Commands Reference

Six atomic commands cover the trader side. The old composite `okx smartmoney trader` has been removed — to get a trader's full picture, fire `performance-by-trader`, `trader-positions`, and `trader-orders-history` in parallel. Use `search-trader` to resolve a nickname to one or more `authorId`s before any of the `--authorId`-keyed tools.

## smartmoney traders-by-filter — Leaderboard Ranking

```bash
okx smartmoney traders-by-filter [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--minPnl <n>] [--minWinRate <r>] [--maxDrawdown <r>] [--minAum <n>] [--after <id>] [--before <id>] [--limit <n>] [--updateTime <ts>] [--json]
```

Pool ranking by numeric thresholds. `authorIds` direct-lookup mode has moved out into its own command (`performance-by-trader`).

### Pool Filter Parameters (numeric thresholds)

Names use `min*` / `max*` prefixes — distinct from the signal-side `*Tier` enum names (e.g. `--pnlTier PNL_TOP20`) so the two surfaces have disjoint flag namespaces. Don't try to pass `--pnlTier` here, and don't try to pass `--minPnl` to a signal command.

| Param | Required | Default | Description |
|---|---|---|---|
| `--sortBy` | No | `pnl` | Sort key: `pnl` or `pnlRatio` |
| `--period` | No | `90` | Time window: `3`, `7`, `30`, `90` (days). Default `90` matches the leaderboard UI. |
| `--minPnl` | No | - | Min PnL (USD), e.g. `10000` = PnL ≥ 10,000 |
| `--minWinRate` | No | - | Min win-rate (decimal). e.g. `0.8` = ≥ 80% |
| `--maxDrawdown` | No | - | Max drawdown (decimal). e.g. `0.1` = ≤ 10% |
| `--minAum` | No | - | Min AUM (USD). e.g. `1000` = AUM ≥ 1,000 |

> Renamed from previous version: `--pnl` → `--minPnl`, `--winRate` → `--minWinRate`, `--asset` → `--minAum`. The new names disambiguate from signal-side `*Tier` enums (since `--pnl` could be confused with `--pnlTier`).

### Pagination Parameters

| Param | Required | Default | Description |
|---|---|---|---|
| `--after` | No | - | Cursor: return results after this `authorId` |
| `--before` | No | - | Cursor: return results before this `authorId` |
| `--limit` | No | `10` | Max results per page (1–100) |
| `--updateTime` | No | latest | Snapshot version key in `yyyyMMddHHmm` (UTC+8). Omit for the latest snapshot (refreshed every ~5 min). |

### Response top-level

| Field | Type | Description |
|---|---|---|
| `data` | Array | Trader rows (see below). |
| `updateTime` | String | **Snapshot version of the leaderboard**, in `yyyyMMddHHmm` (UTC+8, e.g. `202604301815`). Lives at the **response top level** (shared by every item in `data`), NOT inside each row. Refreshed approximately every 5 minutes. Omitted when the wrapper does not provide it. Renamed from the legacy `dataVersion`. |
| `pagination` | Object | `{ hasMore, nextAfter }` cursor metadata. |

### Per-row fields (`data[]`)

| Field | Type | Description |
|---|---|---|
| `authorId` | String | Trader unique ID |
| `nickName` | String | Display name |
| `pnl` | String | Absolute PnL (USD) |
| `pnlRatio` | String | PnL ratio |
| `winRate` | String | Win ratio (0.8 = 80%) |
| `maxDrawdown` | String | Max drawdown (decimal) |
| `asset` | String | Total asset (USD) |
| `onboardDuration` | String | Onboard days |
| `rates` | Array | Historical return time series. Each item: `value` (decimal return rate, e.g. `"-0.06"` = -6%) and `statTime` (`YYMMDD` 6-digit, e.g. `"240726"` — NOT Unix ms; see `context-kg/business/06-leaderboard-smartmoney-api.md` Field Drift §2). |

Top-level `pagination: { hasMore, nextAfter }` — `nextAfter` is the last item's `authorId`. Pass as `--after` for the next page.

### Trader Eligibility Criteria

Traders on the leaderboard must meet all of:
- Public performance status
- Assets ≥ 10,000 USD
- PnL ≥ 1,000 USD (for the chosen `--period`)
- Last trade within 14 days
- KYC fully verified

---

## smartmoney performance-by-trader — PnL / Win-Rate Profile (direct lookup)

```bash
okx smartmoney performance-by-trader --authorIds <id1>,<id2> [--sortBy <pnl|pnlRatio>] [--period <3|7|30|90>] [--json]
```

Direct lookup for a known list of `authorIds`. The upstream endpoint returns the requested traders' performance regardless of leaderboard position. Use after `traders-by-filter`, or to verify a specific user-supplied authorId list.

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorIds` | Yes | - | Comma-separated trader IDs (e.g. `1001,1002,1003`) |
| `--sortBy` | Yes | `pnl` | Result sort key: `pnl` (absolute USD profit) or `pnlRatio` (percentage return) |
| `--period` | Yes | `90` | Performance period: `3`, `7`, `30`, `90` (days). |

Response fields: same shape as the leaderboard rows (`authorId`, `nickName`, `pnl`, `pnlRatio`, `winRate`, `maxDrawdown`, `asset`, `rates[]`, etc.).

---

## smartmoney search-trader — Search Top Traders by Nickname

```bash
okx smartmoney search-trader --keyword <name> [--json]
```

Searches the KOL full-text index by nickname keyword and intersects the recall set with the Top Trader (profitable leaderboard) set. Returns up to **10 matches**, sorted by OKX-platform follower count DESC.

Use this when the user only knows a nickname (e.g. "alice", "小明") and you need the `authorId` before calling any other `--authorId`-keyed tool.

| Param | Required | Default | Description |
|---|---|---|---|
| `--keyword` | Yes | - | Nickname search keyword. Non-empty / non-whitespace. Supports CJK input. |

### Response Fields

| Field | Type | Description |
|---|---|---|
| `authorId` | String | Trader unique ID. Pass to `performance-by-trader` / `trader-positions` / etc. |
| `nickName` | String | Display nickname matched against the keyword. |
| `followerCount` | String | OKX-platform follower count (Twitter excluded). Sort key. |

> Returns an empty array `data: []` when there is no recall, or recall has no intersection with the Top Trader set. The CLI prints "No matching top traders" in that case.

> Backend constraints: only Top Traders are searchable here; non-profitable leaderboard candidates are filtered out. For an authoritative direct lookup by known IDs use `performance-by-trader --authorIds`.

---

## smartmoney trader-positions — Current Open Positions

```bash
okx smartmoney trader-positions --authorId <id> [--instId <id>] [--json]
```

Single trader, current open positions only.

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorId` | Yes | - | Trader's unique author ID (from `traders-by-filter` or `performance-by-trader`) |
| `--instId` | No | - | Filter by instrument. Accepts full instId (e.g. `BTC-USDT-SWAP`) or bare base ccy (e.g. `BTC`) — handler extracts base ccy for the upstream filter. |

> The flag accepts either form; the upstream endpoint filters by base currency only, so the handler extracts it automatically.

### Position Fields

| Field | Description |
|---|---|
| `posId` | Position unique ID |
| `instId` | Instrument (e.g. `BTC-USDT-SWAP`) |
| `instType` | SWAP, SPOT, etc. |
| `posSide` | Raw upstream direction: `long` / `short` / `net` (and legacy `both`). `net`/`both` = net/one-way mode; sign of `pos` encodes direction. |
| `direction` | Derived clean direction: `long` / `short`. Handler computes from `posSide` + sign of `pos`, so agents don't have to branch on the `posSide="net"` net-mode case. Prefer this over `posSide` for direction logic. |
| `posCcy` | Position currency |
| `quoteCcy` | Quote currency |
| `pos` | Position size |
| `lever` | Leverage |
| `avgPx` | Entry avg price |
| `last` | Latest price |
| `notionalUsd` | Position value (USD) |
| `upl` | Unrealized (floating) PnL, in quote currency |
| `pnl` | Realized PnL accrued so far on this position, in quote currency |
| `cTime` | Position open time (Unix ms) |
| `positionIntensity` | Conviction = notionalUsd / trader AUM |

---

## smartmoney trader-positions-history — Closed Positions (realized PnL)

```bash
okx smartmoney trader-positions-history --authorId <id> [--instId <id>] [--after <posId>] [--before <posId>] [--limit <n>] [--json]
```

Closed positions with realized PnL, paginated by `posId` cursor.

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorId` | Yes | - | Trader's unique author ID |
| `--instId` | No | - | Filter by instrument (full instId like `BTC-USDT-SWAP` or bare base ccy like `BTC`; handler extracts base ccy) |
| `--after` | No | - | Cursor: return positions after this `posId` |
| `--before` | No | - | Cursor: return positions before this `posId` |
| `--limit` | No | `10` | Max positions per page (1–100) |

### Closed-Position Fields

| Field | Description |
|---|---|
| `posId` | Position ID |
| `instId` | Instrument |
| `instType` | Instrument business line: `SWAP` / `FUTURES` / `MARGIN` / `SPOT` |
| `ctVal` | Contract value per contract |
| `posSide` | long / short |
| `lever` | Leverage |
| `quoteCcy` | Quote currency the position settled in (e.g. `USDT`) |
| `openAvgPx` / `closeAvgPx` | Open / close avg price |
| `openMaxAmount` / `closeAmount` | Max held / closed size (contracts) |
| `realizedPnl` | Realized PnL |
| `pnl` | Close PnL |
| `pnlRatio` | Realized PnL ratio (decimal) |
| `closeType` | `allClose` / `partClose` / `liquidateClose` / `liquidateReceive` / `adl` |
| `cTime` / `uTime` | Open / close time (Unix ms) |

Top-level `pagination: { hasMore, nextAfter }` — `nextAfter` is the last item's `posId`.

---

## smartmoney trader-orders-history — Order / Fill Records

```bash
okx smartmoney trader-orders-history --authorId <id> [--instId <id>] [--after <ordId>] [--before <ordId>] [--limit <n>] [--json]
```

Order / fill flow. Renamed from the old `smartmoney trades` command to align with the cross-module `*_get_orders` family.

| Param | Required | Default | Description |
|---|---|---|---|
| `--authorId` | Yes | - | Trader's unique author ID |
| `--instId` | No | - | Filter by instrument (full instId like `BTC-USDT-SWAP` or bare base ccy like `BTC`; handler extracts base ccy) |
| `--after` | No | - | Cursor: return orders before this `ordId` |
| `--before` | No | - | Cursor: return orders after this `ordId` |
| `--limit` | No | `10` | Max orders per page (1–100) |

### Order Fields

| Field | Description |
|---|---|
| `ordId` | Order ID |
| `instId` | Instrument |
| `displayId` | Display-form instrument ID used in OKX UI |
| `instType` | SWAP / SPOT |
| `baseName` | Base currency |
| `quoteName` | Quote currency |
| `tradeQuoteCcy` | Quote currency the fill actually settled in |
| `side` | buy / sell |
| `posSide` | long / short |
| `ordType` | limit / market |
| `lever` | Leverage |
| `px` | Order price |
| `avgPx` | Fill avg price |
| `sz` | Order size (币 for SPOT, 张 for SWAP/FUTURES) |
| `value` | Notional in `quoteName` units |
| `cTime` | Order time (Unix ms) |
| `fillTime` | Fill time (Unix ms) |
| `uTime` | Order update time (Unix ms) |

Top-level `pagination: { hasMore, nextAfter }` — `nextAfter` is the last item's `ordId`.

---

## MCP Tool Reference

| CLI Command | MCP Tool |
|---|---|
| `smartmoney traders-by-filter` | `smartmoney_get_traders_by_filter` |
| `smartmoney performance-by-trader` | `smartmoney_get_performance_by_trader` |
| `smartmoney search-trader` | `smartmoney_search_trader` |
| `smartmoney trader-positions` | `smartmoney_get_trader_positions` |
| `smartmoney trader-positions-history` | `smartmoney_get_trader_positions_history` |
| `smartmoney trader-orders-history` | `smartmoney_get_trader_orders_history` |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)