opencode-skills-collection 4.0.73 → 4.0.75

package/bundled-skills/traderspy-market-screener/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: traderspy-market-screener
+description: "Scan the most-traded crypto futures pairs for up to 3 technical conditions in one TraderSpy call, compare coins, and backtest what followed a condition. Use for \"which coins are oversold\"."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/market-screener"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, screener, backtesting, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Market Screener
+
+Two tools, one vocabulary. `screen_symbols` evaluates up to three AND-ed conditions across the
+most-traded pairs (or a list you give it) on one timeframe, in ONE quota unit. `backtest_condition`
+takes the same conditions, one symbol and one timeframe, and reports what price did after every
+past occurrence — with the unconditional baseline so the edge is separated from the tape's drift.
+
+Together they answer the two questions traders actually ask: "what fits this pattern right now?"
+and "has this pattern meant anything before?"
+
+## When to Use
+
+- Use when the user wants to find, filter, rank or compare several coins by technical conditions: "which coins are oversold on the 4h", "what is above its 200 EMA with rising volume", "show me Bollinger squeezes", "find me setups".
+- Use for side-by-side comparison tables such as "compare BTC, ETH and SOL".
+- Use when the user asks what happened after a condition in the past: "how did ETH do after RSI dropped below 30", "is a golden cross on BTC daily actually bullish".
+- Never answer these by calling `get_technical_indicators` coin by coin. For a deep read of one coin use `@traderspy-technical-analysis`.
+
+## The condition vocabulary
+
+A condition is `{ metric, op, value, period?, period2? }`. `op` is `lt` / `gt` (latest value) or
+`crossAbove` / `crossBelow` (a one-bar event: the previous bar was on the other side).
+
+| Metric | Default period | Unit / meaning |
+| --- | --- | --- |
+| `rsi` | 14 | 0–100 |
+| `stochastic` | 14, %D 3 | slow %K, 0–100 |
+| `cci` | 20 | Commodity Channel Index (±100 typical bands) |
+| `mfi` | 14 | 0–100, volume-weighted RSI |
+| `williamsR` | 14 | −100…0 (−80 oversold, −20 overbought) |
+| `adx` | 14 | trend strength; > 25 strong, < 20 absent |
+| `roc` | 12 | rate of change, % |
+| `macdHistogram` | 12, 26 (signal 9) | histogram in price units; `crossAbove 0` = bullish MACD cross |
+| `atrPct` | 14 | ATR as % of price — volatility |
+| `volumeRatio` | 20 | bar volume ÷ average of the previous N bars |
+| `bbPercentB` | 20 (2σ) | 0 = lower band, 1 = upper band; < 0 or > 1 = outside |
+| `bbWidthPct` | 20 | band width as % of the middle — small = squeeze |
+| `priceVsEma` | 50 | % distance of close from EMA(period); > 0 above |
+| `emaSpread` | 50, 200 | % of EMA(period) over EMA(period2); `crossAbove 0` = golden cross |
+| `supertrend` | 10 (×3) | +1 up-trend, −1 down-trend |
+| `changePct` | 24 | % change of close over the last N BARS (on 1h, 24 = one day) |
+| `price` | — | close |
+
+Periods clamp to 2–200. Conditions are AND-ed; there is no OR — run two scans for an OR and merge.
+Unknown metrics are rejected, so stick to the table (the full recipe list is in
+`references/condition-cookbook.md`).
+
+## Screening (`screen_symbols`)
+
+Arguments: `interval` (default 4h), `conditions` (≤ 3), `universe` (5–100 most-traded by 24h
+volume, default 50) OR `symbols` (≤ 100, explicit), `limit` (≤ 50 rows), `sortBy` volume /
+change24h / metric, `sortOrder`.
+
+Choose the timeframe from the user's horizon: intraday → `1h` (or `15m`), swing → `4h`, position →
+`1d`. Widen `universe` to 100 when the user wants small caps or the first scan matched little.
+
+Every result row carries the metric values under their labels (`values["RSI(14)"]`), plus `price`,
+`change24hPct`, `volume24hUsd`, `bias`, `trend`, `rsi14`, `adx14`, `atrPct`, `volumeRatio`,
+`squeeze`. When `matched` > `returned`, say so and offer to raise `limit`.
+
+**Comparison mode**: `symbols` with no `conditions` returns every listed symbol as a table — this is
+how you answer "compare BTC, ETH and SOL" or "how do my five coins look on the daily".
+
+**Translate intent to conditions before calling**, and say what you translated it to:
+
+- "oversold" → `rsi lt 30` (or 35 for a wider net); "deeply oversold" add `bbPercentB lt 0`
+- "overbought" → `rsi gt 70`
+- "in an uptrend" → `priceVsEma gt 0 period 200` + `supertrend gt 0`
+- "with rising volume" → `volumeRatio gt 1.5`
+- "squeezing" → `bbWidthPct lt 4` on 4h (lower on 1h) — then sort by metric ascending
+- "dumped today" → `changePct lt -5 period 24` on 1h, or `period 6` on 4h
+- "golden cross" → `emaSpread crossAbove 0 period 50 period2 200` on 1d
+
+## Backtesting (`backtest_condition`)
+
+Arguments: `symbol`, `interval`, `conditions` (same vocabulary), `horizons` in bars (≤ 4; defaults
+≈ 4h / 1d / 3d: 1h → [4, 24, 72], 4h → [6, 18, 42], 1d → [1, 3, 7]).
+
+The study runs over the whole stored tape — up to 1000 candles, so roughly 41 days on 1h, 166
+days on 4h, 3 years on 1d. An "occurrence" is the FIRST bar of each run where the condition held
+(ten consecutive oversold bars are one episode). For each horizon you get `samples`,
+`avgReturnPct`, `medianReturnPct`, `winRatePct`, `avgMaxUpPct` / `avgMaxDownPct` (average best and
+worst excursion, wick-accurate), `bestPct` / `worstPct`, `baselineAvgReturnPct` (every bar on the
+same tape) and `edgePct` = average − baseline. Also `activeNow`, `currentValues`, `lastOccurrence`,
+and `recent[]` with the last five episodes and their realised returns.
+
+How to read it honestly:
+
+- **Edge and sample size travel together.** `edgePct +1.8 on 27 samples` is a statement;
+  `+6 on 4 samples` is an anecdote, and the tool says so in `warnings`. Never quote the edge alone.
+- **Median vs average**: a positive average with a negative median means a few big winners carried
+  it. Say which.
+- **Excursions are the risk picture**: `avgMaxDownPct −5.1` on a "bullish" setup means the average
+  episode went 5% against you before the horizon ended. That belongs next to the win rate.
+- **Horizons that disagree** (positive at 1d, negative at 3d) usually mean a bounce that fades —
+  report the shape, do not pick the flattering horizon.
+- Recent episodes newer than a horizon are excluded from that horizon (`null` in `recent`), never
+  counted as zero.
+- Coverage limits what the study can see: 41 days of 1h data contains one market regime. A 1d
+  study is the only one that spans cycles.
+
+## Workflows
+
+**"What's oversold right now?"** → one `screen_symbols`. Present the table, then (optional, one more
+call) `backtest_condition` the same condition on the top match so the answer carries "and here is
+what that has meant on this coin before".
+
+**"Find me setups" / "watchlist"** → decide the archetype with the user in one line (mean-reversion
+vs trend-continuation vs breakout), run one scan per archetype (2–3 calls), and present each list
+with the conditions it was built from. Do not promise an outcome for any row.
+
+**"Is X actually bullish?"** → one `backtest_condition` on the coin and timeframe in question;
+if the user names no coin, BTC on 1d is the most meaningful default and say why (longest tape).
+
+**"Compare A, B, C"** → `screen_symbols` with `symbols`, no conditions, on the timeframe they care
+about. Add `get_derivatives` (technical-analysis) only if the question includes funding or
+positioning.
+
+## Presenting
+
+Screen: state the conditions in words and in the tool's labels, the timeframe, and the universe
+("50 most-traded pairs"), then one row per symbol:
+
+| Symbol | Price | 24h % | <metric labels…> | Bias | Trend | ADX | ATR% |
+
+Backtest: one header line (symbol, timeframe, condition, occurrences, coverage), a horizon table —
+
+| Horizon | Samples | Avg % | Median % | Win % | Avg best % | Avg worst % | Baseline % | Edge % |
+
+— then the last episodes and whether the condition is active now. Close with the sample-size
+caveat in your own words.
+
+## Conduct
+
+- A screen is a list of things that are true about the chart right now; a backtest is a sample of
+  what followed in the past. Neither is a recommendation. Present the evidence, note what would
+  invalidate the setup, and leave the trade — and the sizing — to the user.
+- Never turn "70% win rate on 12 samples" into a forecast; historical stats describe their sample.
+- Nothing in this connector trades — no order, close, transfer or withdrawal tool exists by design.
+  If asked to execute, say so plainly; the decision and the trade stay with the user.
+- Quote only what the tools returned; when a symbol is missing from the universe say it was not
+  scanned rather than implying it failed the filter.
+- When a specific trade idea is under discussion, end with one plain sentence that crypto
+  derivatives are high-risk and this is market information, not financial advice.
+
+## Examples
+
+```text
+Which coins are oversold on the 4h?
+Run the screener: RSI under 30 and ADX above 25 on the 4h, top 100 by volume.
+Compare BTC, ETH and SOL on the daily.
+Historically, what happened on SOLUSDT 4h after RSI crossed above 30? Compare it against the baseline over the same tape.
+```
+
+## Limitations
+
+- Needs the hosted TraderSpy MCP server connected in the client (`https://mcp.traderspy.app/mcp`, Streamable HTTP), authorized with OAuth or a personal key from https://traderspy.app/mcp. A free TraderSpy account is enough. Without the server the skill has no data to work from.
+- Tool calls are metered per day: 300 on the free tier, 5,000 on premium.
+- Every tool is read-only. Nothing here places, closes or modifies an order, and there is no withdrawal or transfer tool.
+- The output is market data and analysis for the user's own research, not investment advice.
+- Conditions are AND-ed, at most three per scan, from the fixed metric list above. An OR needs two scans.
+- A scan covers up to the 100 most-traded pairs or an explicit list of up to 100 symbols. A backtest sees at most 1000 stored candles, about 41 days on 1h.
+
+## Related Skills
+
+- `@traderspy-technical-analysis` (called `technical-analysis` in the text above, its upstream ID) - one coin in depth, and `get_derivatives` for funding and positioning
+- `@traderspy-market-briefing` - a market overview that includes a movers scan

package/bundled-skills/traderspy-market-screener/references/condition-cookbook.md

@@ -0,0 +1,70 @@
+# Condition cookbook
+
+Ready-made `conditions` arrays for the intents users actually voice. Combine at most three.
+
+## Mean reversion
+
+| Intent | Conditions |
+| --- | --- |
+| Oversold | `[{"metric":"rsi","op":"lt","value":30}]` |
+| Oversold, wider net | `[{"metric":"rsi","op":"lt","value":35}]` |
+| Deeply oversold (outside lower band) | `[{"metric":"rsi","op":"lt","value":30},{"metric":"bbPercentB","op":"lt","value":0}]` |
+| Oversold in an uptrend (pullback) | `[{"metric":"rsi","op":"lt","value":40},{"metric":"priceVsEma","op":"gt","value":0,"period":200}]` |
+| Overbought | `[{"metric":"rsi","op":"gt","value":70}]` |
+| Overbought and stretched | `[{"metric":"rsi","op":"gt","value":70},{"metric":"bbPercentB","op":"gt","value":1}]` |
+| Washed out on volume | `[{"metric":"williamsR","op":"lt","value":-90},{"metric":"volumeRatio","op":"gt","value":2}]` |
+| Dumped 5%+ in a day (on 1h) | `[{"metric":"changePct","op":"lt","value":-5,"period":24}]` |
+| Dumped 5%+ in a day (on 4h) | `[{"metric":"changePct","op":"lt","value":-5,"period":6}]` |
+
+## Trend
+
+| Intent | Conditions |
+| --- | --- |
+| Above the 200 EMA | `[{"metric":"priceVsEma","op":"gt","value":0,"period":200}]` |
+| Strong uptrend | `[{"metric":"priceVsEma","op":"gt","value":0,"period":200},{"metric":"adx","op":"gt","value":25},{"metric":"supertrend","op":"gt","value":0}]` |
+| Strong downtrend | `[{"metric":"priceVsEma","op":"lt","value":0,"period":200},{"metric":"adx","op":"gt","value":25},{"metric":"supertrend","op":"lt","value":0}]` |
+| Golden cross (event) | `[{"metric":"emaSpread","op":"crossAbove","value":0,"period":50,"period2":200}]` |
+| Death cross (event) | `[{"metric":"emaSpread","op":"crossBelow","value":0,"period":50,"period2":200}]` |
+| Fast EMA stack turning up | `[{"metric":"emaSpread","op":"crossAbove","value":0,"period":9,"period2":21}]` |
+| SuperTrend just flipped up | `[{"metric":"supertrend","op":"crossAbove","value":0}]` |
+| Pullback to the 50 EMA in an uptrend | `[{"metric":"priceVsEma","op":"lt","value":1,"period":50},{"metric":"priceVsEma","op":"gt","value":-1,"period":50},{"metric":"priceVsEma","op":"gt","value":0,"period":200}]` |
+
+## Momentum
+
+| Intent | Conditions |
+| --- | --- |
+| MACD bullish cross (event) | `[{"metric":"macdHistogram","op":"crossAbove","value":0}]` |
+| MACD bearish cross (event) | `[{"metric":"macdHistogram","op":"crossBelow","value":0}]` |
+| Momentum burst | `[{"metric":"roc","op":"gt","value":5},{"metric":"volumeRatio","op":"gt","value":1.5}]` |
+| Stochastic oversold cross up (event) | `[{"metric":"stochastic","op":"crossAbove","value":20}]` |
+| Money flow drying up in an uptrend (divergence hint) | `[{"metric":"mfi","op":"lt","value":40},{"metric":"priceVsEma","op":"gt","value":0,"period":200}]` |
+
+## Volatility
+
+| Intent | Conditions |
+| --- | --- |
+| Bollinger squeeze (4h) | `[{"metric":"bbWidthPct","op":"lt","value":4}]` — sort by metric ascending |
+| Bollinger squeeze (1h) | `[{"metric":"bbWidthPct","op":"lt","value":2.5}]` |
+| Quiet, low-ATR names | `[{"metric":"atrPct","op":"lt","value":1.5}]` |
+| High-ATR names | `[{"metric":"atrPct","op":"gt","value":5}]` |
+| Volume spike right now | `[{"metric":"volumeRatio","op":"gt","value":3}]` |
+
+## Price
+
+| Intent | Conditions |
+| --- | --- |
+| Sub-dollar coins in an uptrend | `[{"metric":"price","op":"lt","value":1},{"metric":"priceVsEma","op":"gt","value":0,"period":200}]` |
+
+## Backtest pairings that read well
+
+- Oversold bounce: `rsi lt 30` on 4h, default horizons → answers "does buying the dip work here".
+- Golden cross: `emaSpread crossAbove 0 (50,200)` on 1d, horizons `[5, 10, 20, 40]`.
+- Capitulation day: `changePct lt -8 period 1` on 1d, horizons `[1, 3, 7, 14]`.
+- Squeeze release: `bbWidthPct lt 3` on 4h — note that a squeeze predicts a move, not a
+  direction; expect small average returns with large excursions both ways.
+
+## Reading `values`
+
+Every row's `values` map is keyed by the tool's label (`RSI(14)`, `EMA spread(50,200)`,
+`Price vs EMA(200)`), and the same labels appear in the `conditions` echo — use them in the table
+header so the user can see exactly what was tested.

package/bundled-skills/traderspy-position-check/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: traderspy-position-check
+description: "Health-check crypto futures positions the user describes, with TraderSpy data: liquidation and stop distance, multi-timeframe read, funding and top-trader side. Reports only; never tells the user to close or add."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/position-check"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, risk-management, futures, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Position Check
+
+A position check answers, in order: how much room is left before this position is taken away
+(liquidation), how much before the user's own plan says it is wrong (stop), what the chart and
+the derivatives market are doing around it, and who else is positioned the same way. Report those
+facts with numbers. The decision — hold, trim, close, add — belongs to the person whose money it
+is.
+
+## When to Use
+
+- Use when the user asks "how's my position", "am I in trouble", "how far am I from liquidation", "should I hold or close" or "review my trades", or asks what you think of their long or short.
+- Use when the user pastes or describes a position, for example "I'm long ETH from 2,400 at 10x".
+- The skill reports and explains. It never tells the user to close, add, hedge or move a stop, and it cannot trade.
+
+## Inputs
+
+The position always comes from the user. TraderSpy has no account tool: it cannot read a balance
+or an open position on any exchange, so never offer to "check the account".
+
+Ask for whatever is missing among side, entry, leverage (and stop / target / the exchange's
+liquidation price if they have them). Size is optional — the analysis works in percentages. The
+current price is the `price` that `get_technical_indicators` returns.
+
+Map the symbol to Binance naming for the data tools: `BTC` → `BTCUSDT`, `kPEPE` → `1000PEPEUSDT`,
+`xyz:AVGO` → `AVGOUSDT`.
+
+## Calls per position (keep it to what matters)
+
+1. `get_technical_indicators` — `intervals: ["1h","4h","1d"]`, `indicators: ["rsi","macd","ema",
+   "atr","adx","supertrend","levels"]`. One call. This gives the trend on three timeframes, ATR
+   for stop sanity and the nearest levels.
+2. `get_derivatives` — up to five coins in ONE call for all positions at once. Funding is a cost
+   or an income for this position; the OI regime says whether the move is being funded.
+3. `get_positions` — `symbol`, `status: "open"`, `limit: 20`. Optional; skip on a tight quota.
+   Tells you whether tracked top traders are on the same side.
+
+Three positions ≈ 3 + 1 (+3) calls. If the quota is tight, do derivatives for all coins first,
+then technicals for the position with the smallest liquidation distance.
+
+## The math (show it, briefly)
+
+- P&L % on margin = (mark − entry) / entry × leverage, sign-flipped for shorts; P&L % on price =
+  the same without leverage. State both when leverage > 1.
+- Distance to liquidation = |liq − mark| / mark. With no liquidation price from the user, approximate:
+  ≈ 100 / leverage % minus a maintenance buffer (say it is approximate; cross margin makes the
+  real distance depend on the whole account).
+- Distance to stop = |stop − mark| / mark, and stop distance in ATRs = |stop − mark| / ATR(14) on
+  the 4h. Under 1 ATR means the stop sits inside normal noise for that timeframe.
+- Funding per day ≈ `funding.ratePct` × 3 on notional; positive rate costs longs and pays shorts.
+
+Bands for the liquidation distance: ≤ 5% →
+"at risk", ≤ 15% → "watch", above → "comfortable". These are labels for a distance, not
+instructions.
+
+## The report
+
+ALWAYS use this template per position:
+
+**<COIN> <SIDE> · <leverage>x · <marginMode>**
+
+- Entry <entry> → mark <mark> (<±x.x%> on price, <±y%> on margin) · uPnL <$, when the size is known>
+- Liquidation <liq> — <d%> away → **<at risk / watch / comfortable>**
+- Stop <stop or "none stated"> — <d%> / <n> ATR(4h) away · Target <if any>
+- Chart: 1h <bias, RSI, trend> · 4h <…> · 1d <…> · confluence <aligned / mixed>
+- Nearest levels: support <price (d%)>, resistance <price (d%)>
+- Derivatives: funding <label, annualized → cost or income for this side>, OI <regime>, top
+  traders <long %> (same side / opposite side)
+- Thesis check: what the position needs to keep working, and the level or reading that would
+  say it has stopped working
+- Scenarios: if price goes to <nearest level against> the position shows <P&L>; at <liquidation>
+  it is gone; at <nearest level for> it shows <P&L>
+
+Then one line naming the position with the least room, and one plain sentence that crypto derivatives are high-risk and this is market information,
+not financial advice.
+
+Facts first, labels second, no verbs of instruction. "The stop sits 0.6 ATR away, inside normal 4h
+noise" is a report; "move your stop" is not.
+
+## Conduct
+
+- Never tell the user to close, hold, add, hedge, move a stop or change leverage. Present
+  distances, scenarios and the invalidation level; the decision is theirs. If they ask "should I
+  close", lay out what supports staying in and what argues against, then hand it back.
+- Distances and scenarios are arithmetic on current prices and levels the tools returned; they are
+  not predictions of where price will go.
+- Nothing in this connector trades — no order, close, transfer or withdrawal tool exists, by
+  design. Say so when asked to act; the decision and any trade stay with the user.
+- Position details the user shares stay in the conversation; do not restate them in later
+  unrelated answers.
+- Quote only tool results and what the user told you; if a coin is not tracked, say so.
+
+Formulas and worked examples: `references/risk-math.md`.
+
+## Examples
+
+```text
+I'm short SOL from 180 at 5x, liquidation around 214. How far is it, and what do the 1h/4h/1d indicators say?
+I'm long ETH from 2,400 at 10x with a stop at 2,250. How does it look?
+Am I in trouble on my SOL short?
+```
+
+## Limitations
+
+- Needs the hosted TraderSpy MCP server connected in the client (`https://mcp.traderspy.app/mcp`, Streamable HTTP), authorized with OAuth or a personal key from https://traderspy.app/mcp. A free TraderSpy account is enough. Without the server the skill has no data to work from.
+- Tool calls are metered per day: 300 on the free tier, 5,000 on premium.
+- Every tool is read-only. Nothing here places, closes or modifies an order, and there is no withdrawal or transfer tool.
+- The output is market data and analysis for the user's own research, not investment advice.
+- TraderSpy cannot see anyone's exchange or TraderSpy account, so every position has to be described or pasted in chat.
+- Without a `liquidationPrice` the liquidation distance is an approximation; under cross margin it depends on the whole account.
+
+## Related Skills
+
+- `@traderspy-technical-analysis` - a full chart read on one of the coins
+- `@traderspy-smart-money` - who else holds the same position

package/bundled-skills/traderspy-position-check/references/risk-math.md

@@ -0,0 +1,60 @@
+# Risk math for position checks
+
+Entry, side and leverage come from the user; mark is the current `price` from the data tools.
+
+## P&L
+
+- Price move % = (mark − entry) / entry × 100, sign-flipped for a SHORT.
+- Return on margin % ≈ price move % × leverage (isolated margin; for cross margin the same figure
+  describes the position, not the account).
+- Unrealized P&L in USD needs the size; compute it only when the user gave one, and say so.
+
+## Liquidation
+
+- Exact: the liquidation price the user's exchange shows → distance % = |liq − mark| / mark × 100.
+- Approximation when the user has none: distance % ≈ 100 / leverage − maintenance margin (assume ~0.5–1%
+  and say "approximately"). 10x → ~9%, 20x → ~4%, 40x → ~2%. Cross margin can be wider (the whole
+  account backs it) or tighter (other positions drain it); the exact figure is the exchange's.
+
+Bands: ≤ 5% at risk · ≤ 15% watch · > 15% comfortable.
+
+## Stop sanity
+
+- Stop distance % = |stop − mark| / mark × 100.
+- In ATRs = |stop − mark| / ATR(14) on the timeframe the user trades (use the 4h if unstated).
+  < 1 ATR: inside normal noise; 1–2 ATR: typical swing stop; > 3 ATR: wide.
+- Reward-to-risk = |target − mark| / |stop − mark| from the CURRENT mark (the original R:R from
+  entry is history).
+
+## Funding
+
+- Per-day cost ≈ `funding.ratePct` × 3 (three 8h settlements) × notional; a positive rate is paid
+  by longs to shorts. Quote it as "≈ $x/day" or "≈ y% APR against / for this side".
+- `avg3dPct` says whether today's rate is typical.
+
+## Reading the chart against the position
+
+- Same-side confluence (a LONG with 1h/4h/1d bullish) → the chart supports the position; the risk
+  is the distance to the stop and to liquidation, not the direction.
+- Opposite-side confluence → the chart is against it; name the level that would have to reclaim.
+- Mixed → identify which timeframe is the user's and lead with that one.
+- Nearest level against the position vs stop: if the stop is beyond a well-touched support (for a
+  long), the plan has structure; if it sits above it, note that the level may be tested first.
+
+## Worked example
+
+LONG ETH 10x cross, entry 2,434, mark 2,534, liq 2,290, stop 2,380, ATR(4h) 62, funding
++0.002%/8h, OI regime `new_longs`, top traders 55% long.
+
+- Price move +4.1%, on margin ≈ +41%.
+- Liquidation 9.6% away → comfortable.
+- Stop 6.1% / 2.5 ATR away → outside 4h noise.
+- Funding ≈ 0.006%/day → negligible cost for a long (≈ 2% APR).
+- Chart 4h bullish, 1d neutral → mixed; the 4h is doing the work.
+- Derivatives: new longs entering; leaders lean long only mildly (55%).
+- Thesis check: the position needs the 4h uptrend to hold; a 4h close below the nearest support
+  (say 2,470) would put the stop in play; above 2,600 resistance the next level is …
+- Scenarios: at 2,470 → +1.5% on price (+15% on margin); at 2,380 (stop) → −2.2% / −22%; at 2,290
+  → liquidated.
+
+Reported as facts and scenarios — no instruction about what to do.

package/bundled-skills/traderspy-smart-money/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: traderspy-smart-money
+description: "Track what top crypto futures traders hold on Binance, Hyperliquid, Bybit and OKX with TraderSpy: elite leaderboard, positions, trader profiles and history. Use for \"what are whales doing\"."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/smart-money"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, smart-money, whale-tracking, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Smart Money
+
+TraderSpy follows thousands of top-ranked accounts on four exchanges and records their positions as
+they open, change and close. This skill turns that feed into answers about positioning and about
+individual traders. Positions are observations of what other people did with their own money —
+present them as evidence, never as instructions.
+
+## When to Use
+
+- Use when the user asks what whales or top traders are buying, shorting or holding, or whether big accounts are long or short a coin.
+- Use when the user asks who ranks highest on an exchange or across exchanges, or wants to research one trader's record and open positions.
+- Use for "smart money", "whale watch" or "what are the pros doing".
+- Not for funding rate, open interest or long/short ratios of the whole market (`@traderspy-technical-analysis`), and not for AI signals (`@traderspy-trading-signals`).
+
+## Tools
+
+| Tool | Use it for | Key arguments |
+| --- | --- | --- |
+| `get_elite_leaderboard` | The cross-exchange top 10 by smart score, with the scoring rationale | none |
+| `get_top_traders` | Ranked traders per exchange and window | `source` all / binance / hyperliquid / bybit / okx, `timeRange` 24h / 3D / 7D / 30D, `rankingType` ROI / PNL, `sortBy` ROI / PNL / SCORE, `limit` ≤ 200 |
+| `get_positions` | The position feed | `status` open / closed / all, `source`, `symbol`, `limit` ≤ 50, `offset` |
+| `get_trader_profile` | One trader: metrics + latest positions | `traderId` AND `source` (see below), `timeRange`, `rankingType` |
+| `get_trader_position_history` | One trader's closed trades, paged | `traderId`, `source`, `page`, `limit` ≤ 50 |
+| `get_market_stats` | Aggregate counts and PnL across all tracked positions | `source`, `period` 4h / 8h / 24h / 7d |
+| `get_exchanges` | Which exchanges are currently tracked | none |
+
+**Always pass `source` with a trader id.** `get_trader_profile` and `get_trader_position_history`
+default to Binance; a Hyperliquid address (`0x…`) or an OKX id looked up on the wrong exchange
+returns nothing. Take `source` from the row you got the id from.
+
+## Reading the data
+
+**Symbols differ per exchange.** Hyperliquid rows use bare coins (`BTC`, `ZEC`) and prefix
+tokenized stocks with `xyz:` (`xyz:AVGO`); Binance, Bybit and OKX rows use `BTCUSDT`. When the
+user asks about "BTC positions", pass `symbol: "BTC"` — the filter matches both `BTC` and
+`BTCUSDT` exactly — and read the `symbol` field before summing anything. Tokenized stocks
+(`xyz:AVGO`) are not reachable through the filter; fetch without `symbol` and pick them out.
+
+**Position rows**: `side` LONG / SHORT, `size` in coins, `entryPrice`, `markPrice`, `leverage`,
+`unrealizedPnl` (open rows) or `pnl` + `roi` (closed rows), `openTime` / `closeTime`, `isOpen`,
+`lastEvent` (`increase`, `partial_close`, or null when the last change was the open itself). Notional ≈ `size × markPrice`; use
+notional, not row count, when you say "whales are net long".
+
+**Freshness.** Binance and Bybit snapshots refresh every 5–15 minutes, Hyperliquid every 15 minutes
+plus live fills, OKX every 10–60 minutes. On a free-tier key the feed is delayed 15 minutes — if
+`get_positions` returns nothing newer than that, say the feed is delayed rather than "no activity".
+
+**Leaderboard rows** (`get_top_traders`) carry the exchange's own ranking snapshot: `roi`, `pnl`,
+`assets` (account size), `winRate` (null on Hyperliquid — the exchange does not publish it),
+`rankings[]` with the same trader across every window, and `smartScore` when TraderSpy has scored
+them. `traderName` is a shortened address when the account has no public name. A trader who is
+#1 on 30-day ROI with `assets` of $5k is a different animal from #19 with $3.4M — quote both.
+
+**Smart score** (`get_elite_leaderboard`, 0–100, recomputed daily): realized PnL 30% (all-time
+blended with the last 30 days), effective win rate 22%, ROI edge 18%, consistency 14%, longevity
+10%, trade depth 6%, plus a recency bonus (up to +9) and a staleness penalty (down to −12 after
+about three weeks idle). `scoreBreakdown` shows each part, `rationale[]` is a ready-made
+plain-language justification, `metrics` has the raw counts (`closedTrades`, `profitFactor`,
+`realizedPnl30d`, `openPositionCount`, `worstDayPnl`). `reliabilityMultiplier` below 1 means a
+short history dragged the score down — say so when a 6-day-old account ranks top-5.
+
+**Market stats** aggregate every tracked position, thousands of them, so `realizedPnl` can be a
+large negative number even when the leaders are winning; the tracked universe includes traders
+who fell off the leaderboard. Use it for counts and the exchange split, not as "smart money is
+losing".
+
+## Workflows
+
+**"What are whales doing in SOL?"** → `get_positions` with `symbol`, `status: open`, `limit` 50.
+Sum notional by side, name the largest two or three accounts with entry and leverage, and note
+how recent the newest entries are. If open rows are few, add `status: closed` for the last day to
+show whether they have been exiting.
+
+**"Who are the best traders right now?"** → `get_elite_leaderboard` first (it is cross-exchange
+and score-based), then `get_top_traders` for a specific exchange or window if the user wants raw
+ROI/PnL. Explain that 7-day ROI rankings reward one lucky week; the smart score is built to
+penalise exactly that.
+
+**"Should I copy trader X?" / "Research this trader"** → `get_trader_profile` + one or two pages of
+`get_trader_position_history`. From the history compute what the user actually needs: win rate
+from closed rows, typical hold time (`closeTime − openTime`), typical leverage, how concentrated
+in one coin, worst single trade, and whether the recent month looks like the all-time record.
+Present it as a profile. Copying is the user's decision — this connector cannot follow anyone.
+
+**"Are the pros long or short?" (whole market)** → `get_positions` `status: open` on the majors
+plus `get_market_stats`; for exchange-wide long/short ratios of ALL accounts use
+`get_derivatives` from technical-analysis instead, which answers that directly.
+
+## Presenting
+
+Positions: one row per position —
+
+| Trader | Exchange | Side | Size (notional) | Entry | Mark | Lev | uPnL | Opened |
+
+Traders: name, exchange, score or rank, window, ROI, PnL, account size, win rate (or "n/a" on
+Hyperliquid), then the two-line rationale. Lead with the number that answers the question, keep
+addresses shortened as returned, and always say which window a ROI belongs to.
+
+## Conduct
+
+- Positions are what other traders did, with their capital, their hedges and their exits, which
+  you cannot see in full. Present them as evidence about positioning, never as a recommendation to
+  mirror them; a leader's long can be one leg of a hedge.
+- Past ROI and win rates describe a past sample — do not present a leaderboard as a forecast of
+  who will win next. Point out short histories and small samples.
+- Nothing in this connector trades or copies. There is no order, follow, transfer or withdrawal
+  tool, by design. If asked to copy or execute a trade, say so plainly; the decision and the trade stay
+  with the user.
+- Quote only what the tools returned; say when data is delayed or a field is null.
+- When the answer is about a specific trade idea, end with one plain sentence that crypto
+  derivatives are high-risk and this is market information, not financial advice.
+
+For exchange-specific quirks and refresh cadences read `references/exchange-notes.md`.
+
+## Examples
+
+```text
+What are the top traders long and short right now?
+What are whales doing in SOL?
+Who is at the top of the Hyperliquid leaderboard right now, and what are they positioned in? Then show me the position history of the top one.
+```
+
+## Limitations
+
+- Needs the hosted TraderSpy MCP server connected in the client (`https://mcp.traderspy.app/mcp`, Streamable HTTP), authorized with OAuth or a personal key from https://traderspy.app/mcp. A free TraderSpy account is enough. Without the server the skill has no data to work from.
+- Tool calls are metered per day: 300 on the free tier, 5,000 on premium.
+- Every tool is read-only. Nothing here places, closes or modifies an order, and there is no withdrawal or transfer tool.
+- The output is market data and analysis for the user's own research, not investment advice.
+- On a free key, position rows are delayed 15 minutes. Leaderboards, profiles and stats are not delayed.
+- It sees only the accounts TraderSpy tracks on Binance, Hyperliquid, Bybit and OKX, not what the same traders hold elsewhere, so a tracked long can be one leg of a hedge.
+
+## Related Skills
+
+- `@traderspy-technical-analysis` (called `technical-analysis` in the text above, its upstream ID) - `get_derivatives` for exchange-wide funding, open interest and long/short ratios
+- `@traderspy-trading-signals` - AI signals rather than trader positions

package/bundled-skills/traderspy-smart-money/references/exchange-notes.md

@@ -0,0 +1,40 @@
+# Exchange notes for the smart-money feed
+
+| Exchange | `source` | Trader id looks like | Symbols | Refresh | Notes |
+| --- | --- | --- | --- | --- | --- |
+| Binance | `binance` | opaque leaderboard id | `BTCUSDT` | positions every 5–10 min | Largest tracked set (~5k positions); leaderboard is opt-in, so it is the traders who chose to be public |
+| Hyperliquid | `hyperliquid` | `0x` EVM address | bare coin `BTC`, `kPEPE`-style 1000x coins, `xyz:AVGO` for tokenized stocks | fills live via WebSocket, snapshots every 15 min | Fully on-chain, so positions are exact; `winRate` is null because the venue does not publish it |
+| Bybit | `bybit` | opaque id | `BTCUSDT` | every 10–15 min | Smaller tracked set |
+| OKX | `okx` | 16-hex id | `BTCUSDT` | every 10 min – 1 h | Copy-trade leaders; names and avatars are public; many high-frequency scalpers with 90%+ win rates and tiny per-trade ROI |
+
+## Elite leaderboard (`get_elite_leaderboard`)
+
+- Recomputed daily (00:10 Europe/Istanbul); `lastRunAt` says when. Not intraday.
+- `tier` is the exchange's own badge where one exists (OKX leaders show Silver / Bronze / Regular);
+  null on venues without badges.
+- `algorithmDetails[]` in the response documents every weight — quote it when the user asks how
+  the score works instead of paraphrasing from memory.
+- `summary.totalTrackedTraders` vs `tradersWithClosedTrades` tells you how many accounts actually
+  have a closed-trade record behind their score.
+- A trader can top the score with a negative `effectiveRoi` if their realized PnL is huge — the
+  score rewards money made, not percentage. Say which when the two disagree.
+
+## Reading a trader's history for a "should I copy" profile
+
+From `get_trader_position_history` rows (`symbol, side, size, entryPrice, closePrice, leverage,
+pnl, roi, openTime, closeTime`):
+
+- win rate = rows with `pnl > 0` ÷ rows
+- average hold = mean of `closeTime − openTime`, expressed in hours or days
+- concentration = share of rows (or of |pnl|) in the single most-traded symbol
+- worst trade = min `pnl`; compare it with the median win to show the shape of the distribution
+- leverage habit = median `leverage`; flag anything ≥ 20× explicitly
+- recency = share of rows in the last 30 days; a great all-time record with nothing recent is a
+  dormant account
+
+Two pages of 50 rows are plenty for a profile. State the sample size.
+
+## Free tier
+
+Position rows are filtered to those older than 15 minutes on a free key. Leaderboards, profiles and
+stats are not delayed.