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 add-profile AK=<your_api_key> SK=<your_secret_key> PP=<your_passphrase> name=live
   # or interactive wizard:
   okx config init

3. Verify: okx --profile live smartmoney traders --limit 5

---

Credential & Profile Check

Run okx config show before any authenticated command.

• Error or no configuration → stop, guide user to run okx config init, wait for completion.
• Credentials configured → proceed.

On 401 errors: stop immediately, tell the user their credentials may be invalid or expired, guide them to update ~/.okx/config.toml (do NOT ask them to paste credentials into chat), then verify with okx config show and retry.

---

Skill Routing

---

Command Index (5 commands, all read-only)

Trader Data

Signal Data

Note: Prefer --ts (e.g. --ts $(date +%s)000 for latest snapshot) for overview / signal / signal-history; --dataVersion is an alternative for replaying a prior snapshot. At least one of the two must be provided; if both are sent, --ts wins.

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 command: see Credential & Profile Check. Always use --profile live silently.

Step 1 — Identify intent

Trader discovery / ranking:

• "推荐交易员" / "top traders" / "牛人榜" → smartmoney traders with sorting/filtering. See {baseDir}/references/trader-commands.md.
• "看看某个交易员" / "trader detail" → smartmoney trader --authorId <id>. See {baseDir}/references/trader-commands.md.

Signal analysis:

• "BTC 聪明钱信号" / "smart money signal for BTC" → smartmoney signal. See {baseDir}/references/signal-commands.md.
• "聪明钱总览" / "smart money overview" → smartmoney overview. See {baseDir}/references/signal-commands.md.
• "信号趋势" / "signal trend over time" → smartmoney signal-history. See {baseDir}/references/signal-commands.md.

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.
• Signal availability: Signal commands (overview, signal, signal-history) require either --ts (preferred — use $(date +%s)000 for latest) or --dataVersion (for historical snapshot replay). If both are sent, --ts wins.

For number/time formatting and response structure conventions, read {baseDir}/references/templates.md.

Signal Commands Reference

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

smartmoney signal — Consensus Signal

okx smartmoney signal [--instId <id>] [--instCcy <ccy>] [--ts <ms> | --dataVersion <ver>] [--sortType <type>] [--period <d>] [--pnl <tier>] [--winRatio <tier>] [--maxRetreat <tier>] [--asset <tier>] [--lmtNum <n>] [--authorIds <ids>] [--json]

Aggregates pool traders' positions for a single currency to produce long/short ratio, weighted ratio, avg entry price, capital flow, trend deltas, and market context.

At least one of `--instId` (e.g. `BTC-USDT-SWAP`) or `--instCcy` (e.g. `BTC`, SPOT/SWAP only) is required. --instId takes precedence if both are set.

Parameters

Pool filter params (sortType, period, pnl, winRatio, maxRetreat, asset) also apply.

Signal Filter Enum Values

All signal endpoints share these enum-based pool filters:

All enums are case-insensitive. Invalid values silently fall back to default.

Response Fields (27 fields, single object in data[0])

---

smartmoney signal-history — Signal Timeline

okx smartmoney signal-history --instId <id> [--ts <ms> | --dataVersion <ver>] [--granularity <1h|1d>] [--limit <n>] [--sortType <type>] [--period <d>] [--pnl <tier>] [--winRatio <tier>] [--maxRetreat <tier>] [--asset <tier>] [--json]

Returns historical signal snapshots for a given instrument. Sorted by ts DESC. Useful for trend analysis and backtesting.

Parameters

Pool filter params (sortType, period, pnl, winRatio, maxRetreat, asset) and enum tiers also apply.

Response Fields (10 fields per item, array data[], sorted by ts DESC)

---

smartmoney overview — Multi-Currency Overview

okx smartmoney overview [--ts <ms> | --dataVersion <ver>] [--instType <type>] [--instCcyList <ccys>] [--instCcy <ccy>] [--topInstruments <n>] [--sortType <type>] [--period <d>] [--pnl <tier>] [--winRatio <tier>] [--maxRetreat <tier>] [--asset <tier>] [--lmtNum <n>] [--json]

Returns aggregated signal snapshots for top currencies, ranked by tradersWithPosition (most-watched first).

Parameters

Pool filter params (sortType, period, pnl, winRatio, maxRetreat, asset) and enum tiers also apply.

Filter order: SQL first limits by topInstruments → then filters by instCcyList currency prefix → topNUsed = final result count. So topInstruments=3 & instCcyList=BTC may return < 3 items.

Response Fields (11 fields per item, array data[])

---

MCP Tool Reference

Templates & Formatting Reference

Trader Ranking Table Template

Trader Profile Template

=== {nickName} ===
Author ID:    {authorId}
PnL:          ${pnl} ({pnlRatio}%)
Win Rate:     {winRatio}%
Max Drawdown: {maxRetreat}%
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

smartmoney traders — Leaderboard

okx smartmoney traders [--sortType <type>] [--period <d>] [--pnl <n>] [--winRatio <r>] [--maxRetreat <r>] [--asset <n>] [--authorIds <ids>] [--after <id>] [--before <id>] [--limit <n>] [--json]

Pool Filter Parameters (shared across all commands)

Leaderboard-Specific Parameters

Response Fields

Trader Eligibility Criteria

Traders on the leaderboard must meet all of:

• Public performance status
• Assets >= 10,000 USD
• PnL >= 1,000 USD (for corresponding period)
• Last trade within 14 days
• KYC fully verified

---

smartmoney trader — Trader Detail (Composite)

okx smartmoney trader --authorId <id> [--period <d>] [--instCcy <ccy>] [--tradeLimit <n>] [--json]

Aggregates three API calls in parallel: 1. Profile: leaderboard stats for this trader 2. Current positions: open positions with leverage, entry price, PnL 3. Trade records: recent order history

Composite Response Structure

The --json output wraps three sub-results:

{
  "endpoint": "smartmoney_get_trader_detail (composite)",
  "requestTime": "2026-04-09T12:00:00.000Z",
  "data": {
    "profile": [ { ...leaderboard fields... } ],
    "positions": [ { ...position fields... } ],
    "trades": [ { ...trade record fields... } ]
  }
}

Current Position Fields

Trade Record Fields

---

MCP Tool Reference

Smart Money Workflows

1. Recommend Top Traders

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

okx --profile live smartmoney traders --period 30 --sortType pnl --limit 10 --json

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

Highlight:

• Highest absolute PnL
• Best return ratio (pnlRatio)
• Best risk-adjusted (high winRatio + low maxRetreat)

---

2. Drill Down into a Trader

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

okx --profile live smartmoney trader --authorId <id> --json

Present profile summary, then current positions table, then recent trades table.

---

3. Search for a Specific Trader

User: "搜索交易员 XXX"

okx --profile live smartmoney traders --authorIds <id1>,<id2> --json

If user provides nickName instead of authorId, search is not supported by API — inform user they need the authorId.

---

4. Filter Traders by Criteria

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

okx --profile live smartmoney traders --winRatio 0.8 --period 30 --sortType pnl --limit 10 --json

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

okx --profile live smartmoney traders --maxRetreat 0.1 --period 30 --limit 10 --json

---

5. Smart Money Signal for a Currency

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

# Use --ts with current timestamp in ms
ts=$(date +%s)000

# Prefer --instId; --instCcy (e.g. BTC) is also accepted for SPOT/SWAP, but --instId takes precedence
okx --profile live smartmoney signal --ts $ts --instId BTC-USDT-SWAP --json

Present signal summary (all fields are flat in data[0]):

• Long/short ratio: longRatio, weightedLongRatio, longTraders, shortTraders
• Win rates: avgLongWinRatio, avgShortWinRatio
• Trend deltas: vs1h, vs24h, vs7d
• Entry prices: smartMoneyLongAvgEntry, smartMoneyShortAvgEntry
• Capital: longNotionalUsdt, shortNotionalUsdt, netNotionalUsdt, totalNotionalVs24h
• Market context (reserved): currentPrice, priceChange24h, fundingRate, openInterest, longShortAccountRatio

---

6. Multi-Currency Overview

User: "聪明钱总览" / "smart money overview"

ts=$(date +%s)000
okx --profile live smartmoney overview --ts $ts --json

Present top currencies by smart money activity. Table columns: instId, tradersWithPosition, longRatio, weightedLongRatio, netNotionalUsdt, vs24h.

---

7. Signal Trend Analysis

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

ts=$(date +%s)000
okx --profile live smartmoney signal-history --instId BTC-USDT-SWAP --ts $ts --granularity 1d --json

Present as time series table showing: ts, longRatio, weightedLongRatio, tradersWithPosition, netNotionalUsdt, totalNotionalUsdt, tradersQualified.

---

8. Cross-Skill: Smart Money + Market Context

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

# Parallel execution:
# 1. Smart money signal (already includes marketContext). Prefer --instId; --instCcy (SPOT/SWAP only) is also accepted, but --instId takes precedence.
okx --profile live smartmoney signal --ts $(date +%s)000 --instId BTC-USDT-SWAP --json

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

Combine: compare smart money avg entry vs current price, interpret long/short ratio + trend.

---

9. Recommend and Deep Dive

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

# Step 1: Get top traders
okx --profile live smartmoney traders --period 30 --sortType pnl --limit 5 --json

# Step 2: Pick best candidate, get full detail
okx --profile live smartmoney trader --authorId <top_trader_id> --json