Okx Cex Smartmoney

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`. Use metadata.version from this file's frontmatter as the reference for Step 2.

Prerequisites

1. Install okx CLI:

   npm install -g @okx_ai/okx-trade-cli

2. Configure credentials:

   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 Step 2 and remembered for the session.

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

---

Command Index (10 commands, all read-only)

Trader family (6)

Signal / coin family (4)

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. 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.

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)

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.

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 below) apply.

Response Fields (per instrument, array data[])

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

Outer fields

`notional` group (capital flow)

`longShortRatio` group (ratio + historical deltas)

`winRate` group (capability — driven by period)

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)

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?".

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)

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.

Pool filter params (see Signal Filter Enums below) apply.

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

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)

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.

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.

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

Templates & Formatting Reference

Trader Ranking Table Template

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

Trade Record Table Template

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

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 authorIds before any of the --authorId-keyed tools.

smartmoney traders-by-filter — Leaderboard Ranking

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.

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

Response top-level

Per-row fields (data[])

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)

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.

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

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.

Response Fields

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

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

Single trader, current open positions only.

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

Position Fields

---

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

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.

Closed-Position Fields

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

---

smartmoney trader-orders-history — Order / Fill Records

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.

Order Fields

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

---

MCP Tool Reference

Smart Money Workflows

1. Recommend Top Traders

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

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:

# 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:

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"

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:

# 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"

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

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

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"

# 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 这几个币的共识"

# 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?"

# 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):

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?"

# 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"

# 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"

# 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 成交记录"

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).