opencode-skills-collection 4.0.74 → 4.0.76

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.

package/bundled-skills/traderspy-technical-analysis/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: traderspy-technical-analysis
+description: "Read one crypto futures pair with TraderSpy: 19 indicators on up to 3 timeframes in one call, key levels, funding, open interest and positioning. Use for \"analyse BTC\" or \"is SOL oversold\"."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/technical-analysis"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, technical-analysis, indicators, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Technical Analysis
+
+One good read of a chart is three things in order: where price is in its structure (trend and
+levels), what momentum and volatility are doing, and how the derivatives market is positioned
+around it. TraderSpy gives all three in at most two calls. Spend the calls well — the user's quota
+is finite — and quote the numbers, not adjectives.
+
+## When to Use
+
+- Use when the user asks about a coin's chart, trend, momentum, support and resistance, or where a level such as the 200 EMA sits.
+- Use for "analyse BTC", "how does SOL look", "is X overbought / oversold", "what do the indicators say" or "is this a good entry", even when the user only names a coin.
+- Use when the question is whether funding is high or open interest is building, or when the user wants price or candle data.
+- For scanning many coins by conditions use `@traderspy-market-screener`; for whale positions use `@traderspy-smart-money`.
+
+## Tools
+
+| Tool | Use it for | Key arguments |
+| --- | --- | --- |
+| `get_technical_indicators` | The chart read | `symbol`, `intervals` (≤ 3) or `interval`, `indicators` (≤ 19), `periods`, `history` 0–20 |
+| `get_derivatives` | Funding, open interest, positioning | `symbols` (≤ 5 Binance USDⓈ-M perps; bare `BTC` is fine) |
+| `get_price` | Live price, 24h high/low/volume/change | `symbols` (≤ 20) |
+| `get_candles` | Raw OHLCV | `symbol`, `interval` 1m/5m/15m/1h/4h/1d, `limit` ≤ 500 |
+| `get_tracked_symbols` | Coverage check | none — only when a symbol returns no data |
+
+Symbols are Binance Futures names: `BTCUSDT`, `SOLUSDT`, `1000PEPEUSDT` (1000x-prefixed small
+caps), and tokenized equities/ETFs such as `AAPLUSDT` or `SPYUSDT`. Append `USDT` to a bare coin.
+Hyperliquid-only perps (e.g. HYPE) are tracked under the same naming.
+
+## Making the call count
+
+- **Multi-timeframe is one quota unit.** For any "how does X look" question pass
+  `intervals: ["1h","4h","1d"]` (or `["15m","1h","4h"]` for an intraday user) and get a
+  `confluence` verdict — never three separate calls.
+- **Pick indicators for the question.** Default `rsi, macd, ema, bollinger` covers momentum and
+  trend. Add `levels` + `pivots` whenever the user cares about entries, targets or "where is
+  support"; `atr` for stop distance and volatility; `adx` for trend strength; `supertrend` for a
+  clean trend state; `obv` / `mfi` when volume confirmation matters; `ichimoku` / `keltner` only
+  when asked. Eight to ten well-chosen indicators is a full read; all 19 is noise.
+- **`periods`** lets you honour the user's settings (`{"ema":[9,21,55,200],"rsi":7}`); an unknown
+  key is rejected, so use the documented names only.
+- **Add `get_derivatives`** when the question involves "why is it moving", crowding, funding,
+  open interest, leverage, liquidations, or when the user is about to lean on a directional call —
+  candles cannot see positioning.
+- `get_candles` is for when the user wants the data itself (to chart, export or compute something
+  custom). Do not fetch candles to eyeball indicators the technicals tool already computes.
+
+## Reading the response
+
+**Shape.** One timeframe → top-level `indicators` + `summary`. Several → `timeframes[]` (each
+with `interval`, `price`, `candles`, `indicators`, `summary`) plus `confluence` `{ aligned, bias,
+byInterval }`; the top-level `interval`/`price` then name the first timeframe only. `settings`
+echoes what was computed; `warnings[]` lists anything that was thinned or missing.
+
+**Every indicator** carries `value`, `previous`, `direction` (rising / falling / flat) and a short
+`series` (oldest → newest), plus its own fields — `zone` on RSI/Stochastic/CCI/MFI/Williams,
+`crossover` on MACD/Stochastic, `stack`/`pricePosition` on EMA, `±DI` and `strength` on ADX,
+`trend`/`flipped`/`barsSinceFlip` on SuperTrend, `divergence` on RSI/MACD/OBV. `{ value: null,
+reason: "insufficient_data" }` means the tape is too short for that period — say so, do not
+substitute.
+
+**`summary` is the spine of the read.** `bias` (bullish / bearish / neutral) is computed from a
+FIXED set (RSI 14, MACD, EMA 20/50/200, ADX 14, ATR 14, BB 20/2, volume 20) regardless of what
+you requested, so it is comparable between calls; `score` is its internal vote (|score| ≥ 30 sets
+a bias). `trend` (direction, strength, emaStack, priceVsEma200), `momentum` (rsiZone, macdState),
+`volatility` (atrPct, atrPercentile 0–100, squeeze, state), `volume.ratioVsAverage`, `patterns[]`
+(candlestick finders on the last two bars) and `notes[]` — plain-language sentences written to be
+quoted. Build the answer from the notes, then add the numbers.
+
+**`levels`** (nearest three per side from swing highs/lows over 300 bars): `price`, `touches`,
+`distancePct`; `range.positionPct` (0 = at the low of the lookback, 100 = at the high);
+`fibonacci` (the dominant leg with `retracedPct` and the nearest level above/below);
+`volumeProfile` (`poc`, value area, `pricePosition`). **`pivots`** are classic floor pivots from
+the previous DAILY candle whatever the timeframe. Together they give you a levels table; distance
+in % is what a user can act on.
+
+**`confluence.aligned`** is true only when every timeframe with data agrees on a non-neutral bias.
+"Aligned bearish on 1h/4h/1d" is a strong statement; "4h bullish, 1d neutral" is a pullback
+question. Say which.
+
+**Derivatives** (`get_derivatives`): `funding.label` — `extreme_longs_paying` / `longs_paying` /
+`neutral` / `shorts_paying` / `extreme_shorts_paying` (longs pay at ≥ +0.03% per 8h, extreme at
+≥ +0.10%; shorts pay at ≤ −0.01%, extreme at ≤ −0.05%; Binance's baseline is +0.01%; quote
+`annualizedPct`); `openInterest.regime` — `new_longs` / `short_covering` / `new_shorts` /
+`long_liquidation` / `flat` (needs ≥ 1% OI and ≥ 0.5% price change over 24h);
+`positioning.label` — `long_heavy` (long/short ratio ≥ 1.5, i.e. ≥ 60% long) / `balanced` /
+`short_heavy` (≤ 0.67, i.e. ≤ 40% long), read from the top-trader POSITION ratio first;
+`takerBuySellRatio` is the last hour's aggressor flow. Data is at most 60 s old. `notes[]` are
+quotable. Details in `references/derivatives-guide.md`.
+
+## Presenting
+
+For a single-coin read ALWAYS use this order, and keep it to what the user asked:
+
+1. **Price line** — symbol, price, time of the read, 24h change if you fetched it.
+2. **Per timeframe, one line each** — bias, trend (EMA stack and ADX), momentum (RSI zone, MACD
+   state), volatility (ATR %, squeeze), with the key number after each label.
+3. **Confluence** — aligned or not, and what the disagreement means.
+4. **Levels table** — nearest support and resistance with distance %, the pivot, the nearest
+   Fibonacci level, the value-area edge if price is near it.
+5. **Derivatives line** (if fetched) — funding label + annualized, OI regime, top-trader long %.
+6. **What would change the read** — the one or two levels or readings that flip the picture
+   (e.g. "a 4h close above 79,325 resistance with OI rising would turn the 4h bias bullish").
+7. One plain sentence: crypto derivatives are high-risk; this is market information, not advice.
+
+Use `RSI(14) 41.3 — neutral, falling` style labelling so the period and the direction are always
+visible. Percentages to one decimal; prices to the precision the tool returned.
+
+## Conduct
+
+- Describe the chart; do not prescribe the trade. If the user asks "is this a good entry", answer
+  with what supports the entry, what argues against it, where the invalidation sits, and hand the
+  decision back. Never tell the user to buy, sell, size or leverage.
+- Indicators describe the past bars they were computed on; do not present a bias as a forecast or
+  imply any outcome is assured.
+- 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. If an indicator is `insufficient_data` or a symbol is not
+  tracked, say so instead of estimating.
+- 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 — once per
+  answer.
+
+Per-indicator fields and conventional readings: `references/indicator-guide.md`.
+
+## Examples
+
+```text
+Analyse BTC on the 1h, 4h and 1d with funding and open interest.
+Is SOL overbought? Where are the nearest support and resistance levels?
+Where is the 200 EMA on ETH, and is funding stretched?
+```
+
+## 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.
+- A multi-timeframe read is one tool call; adding derivatives makes it two.
+- Symbols use Binance Futures naming (`BTCUSDT`, `1000PEPEUSDT`). `get_derivatives` covers Binance USDⓈ-M perpetuals, up to five per call.
+
+## Related Skills
+
+- `@traderspy-market-screener` - many coins at once, and backtests of a condition
+- `@traderspy-smart-money` - what tracked top traders hold
+- `@traderspy-position-check` - the same read applied to an open position

package/bundled-skills/traderspy-technical-analysis/references/derivatives-guide.md

@@ -0,0 +1,57 @@
+# Derivatives guide — `get_derivatives`
+
+Source: Binance USDⓈ-M perpetual futures public endpoints, snapshot cached 60 s. One entry per
+symbol; an unknown or non-Binance symbol comes back as `{ symbol, error, message }`.
+
+## Fields
+
+- `markPrice`, `indexPrice`, `premiumPct` — mark vs index; a persistent positive premium is
+  another face of long crowding.
+- `funding`: `rate` (raw, per 8h), `ratePct`, `annualizedPct`, `nextFundingTime`,
+  `minutesToNextFunding`, `avg24hPct`, `avg3dPct`, `label`.
+- `openInterest`: `contracts`, `valueUsd`, `change4hPct`, `change24hPct`, `priceChange24hPct`,
+  `regime`.
+- `positioning`: `globalLongShortRatio`, `globalLongPct` (all accounts), `topTraderLongShortRatio`,
+  `topTraderLongPct` (top traders, by position size), `takerBuySellRatio` (last hour),
+  `label`.
+- `notes[]` — the interpretation in sentences; quote them.
+
+## Labels
+
+| `funding.label` | Rule (per 8h) | Reading |
+| --- | --- | --- |
+| `extreme_shorts_paying` | ≤ −0.05% | Shorts crowded and paying heavily; squeeze risk |
+| `shorts_paying` | ≤ −0.01% | Shorts paying longs |
+| `neutral` | between −0.01% and +0.03% (Binance's baseline is +0.01%) | No crowding signal |
+| `longs_paying` | ≥ +0.03% | Longs paying shorts — leverage leaning long |
+| `extreme_longs_paying` | ≥ +0.10% | Longs crowded and paying heavily; long-squeeze / flush risk |
+
+Quote `annualizedPct` alongside — "0.05%/8h" means little to most readers, "≈ 55% APR" does.
+
+| `openInterest.regime` | OI 24h | Price 24h | Reading |
+| --- | --- | --- | --- |
+| `new_longs` | up | up | Fresh money buying; trend being funded |
+| `short_covering` | down | up | Rally driven by shorts closing — less durable |
+| `new_shorts` | up | down | Fresh shorts pressing; trend being funded to the downside |
+| `long_liquidation` | down | down | Longs being flushed — capitulation-type move |
+| `flat` | < 1% OI or < 0.5% price | No meaningful OI story |
+
+| `positioning.label` | Rule | Reading |
+| --- | --- | --- |
+| `long_heavy` | long/short ratio ≥ 1.5 (≈ 60%+ long) | Leaders leaning long |
+| `balanced` | between | No lean |
+| `short_heavy` | ratio ≤ 0.67 (≈ 40% or less long) | Leaders leaning short |
+
+Top-trader positioning (by position size) is read first because it is the informed cohort; the
+all-account ratio shows the crowd. When they disagree ("top traders 69% long, all accounts 45%
+long"), that disagreement is the interesting sentence.
+
+## Combining with the chart
+
+- Chart bullish + `new_longs` + `neutral` funding: a trend with fuel and no crowding.
+- Chart bullish + `extreme_longs_paying`: extended; flush risk is the caveat to state.
+- Chart bearish + `short_covering` bounce: a relief rally, not a reversal, until OI rebuilds.
+- `long_liquidation` with `extreme_shorts_paying` afterwards: the flush may be done; watch whether
+  OI rebuilds.
+
+These are conventional readings to explain the data, not predictions.