TraderSpy

View saved version →

---
name: market-briefing
description: Build a concise crypto market briefing from live TraderSpy data in a handful of tool calls — BTC/ETH/SOL price and 24h change, funding and open interest on the majors, which way top traders and the crowd lean, the freshest AI signals with their recent hit rate, and what the market screener flags right now (top movers, oversold / overbought names, squeezes). Use this whenever the user asks "what's happening in crypto", "market update", "morning brief", "how's the market today", "anything interesting right now", "give me an overview", "weekly recap", or opens a conversation with a vague "so, crypto?" — even casually. Not for a deep dive on one coin (technical-analysis), one trader (smart-money) or one signal (trading-signals).
---

A briefing is a fixed set of questions answered with fresh numbers, in an order a trader can scan
in thirty seconds: where are the majors, how is the market positioned, what is the signal engine
seeing, what stands out on the screener. The value is in the selection and the brevity, not in the
volume of data — every tool call costs the user quota, so the playbook below is deliberately
tight.

## The playbook (6 calls, all read-only)

1. **Majors** — `get_price` with `["BTCUSDT","ETHUSDT","SOLUSDT"]` plus any coins the user has
   mentioned in the conversation (≤ 20 per call). Price, 24h change, 24h range.
2. **Positioning** — `get_derivatives` with `["BTC","ETH","SOL"]` (add up to two of the user's
   coins). Funding label and annualized rate, open-interest change and regime, top-trader long
   share, taker flow. The `notes[]` are written to be quoted.
3. **Movers** — `screen_symbols` with no conditions, `sortBy: "change24h"`, `limit: 50`, `universe:
   50`, `interval: "4h"`. One call returns all 50 most-traded pairs sorted by 24h change: the top
   five are the gainers, the last five the losers.
4. **What is stretched** — `screen_symbols` with `[{"metric":"rsi","op":"lt","value":30}]` on 4h,
   `limit: 5`. If it returns nothing, flip to `rsi gt 70` — one of the two usually has names.
5. **Signal engine** — `get_signal_stats` with `period: "24h"` (or `7d` for a weekly recap).
6. **Freshest ideas** — `get_signals` with `limit: 5`.

Smart-money lean is already in step 2 (`positioning.topTraderLongPct`); add `get_positions`
(`status: open`, `limit: 20`) only when the user asks who specifically is positioned how.

**Quota-aware variants.** If the user is on a free key or asks for "just the headline", run steps
1, 2 and 5 only (three calls) and say what you skipped. For a weekly recap use `7d` in step 5 and
`interval: "1d"` in steps 3–4.

If any call fails or returns empty, keep the section with a one-line "unavailable right now" note
rather than dropping it silently — a briefing with a hole is more honest than one that quietly
narrowed.

## Reading the pieces

- **Funding**: near the 0.01%/8h baseline is neutral; clearly positive means longs pay shorts (a
  crowded long is a risk, not a signal); negative means shorts pay. Quote the annualized figure —
  it is the number people feel.
- **Open interest regime** (`openInterest.regime`): `new_longs` (OI up, price up), `short_covering`
  (OI down, price up), `new_shorts` (OI up, price down), `long_liquidation` (OI down, price down),
  `flat`. This is the one line that explains WHY the majors moved.
- **Top-trader long share**: the tool labels `long_heavy` at a long/short ratio ≥ 1.5 (≈ 60%+
  long) and `short_heavy` at ≤ 0.67 (≈ 40% or less); in between call it balanced. Top-trader
  positioning is the more informative one; the all-account ratio shows the crowd.
- **Signal stats**: `winRate` is hits ÷ (hits + stops) on signals created in the window; say
  `total` and `pending` next to it, and treat a 24h window with fewer than ~10 resolved signals as
  a small sample.
- **Movers** are the most-traded pairs by 24h volume sorted by change — a liquid-names list, not
  an all-market list. Say so if a small cap the user follows

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: market-screener
description: Scan the whole crypto futures market in one call and test what a setup did historically, using TraderSpy's screener and backtest. "Which coins are oversold on the 4h", "what is above its 200 EMA with rising volume", "show me Bollinger squeezes", "biggest losers today with RSI under 30", "find me setups / a watchlist", side-by-side comparison tables ("compare BTC, ETH and SOL"), and event studies ("how did ETH do after RSI dropped below 30", "is a golden cross on BTC daily actually bullish", "what usually follows a −5% day on SOL"). Use this whenever the user wants to find, filter, rank or compare several coins by technical conditions, or asks what happened after a condition in the past. Never answer these by calling get_technical_indicators coin by coin. For a deep read of ONE coin use technical-analysis.
---

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

## 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 `bbPercen

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: position-check
description: Health-check crypto futures positions the user describes or pastes in chat ("I'm long ETH from 2,400 at 10x") with TraderSpy market data. TraderSpy cannot see anyone's account, so the position always comes from the user. Produces a structured risk report per position — distance to liquidation and to the stop, where price sits versus entry, the multi-timeframe technical read, funding cost or benefit and the open-interest regime, whether top traders are on the same or the opposite side, and what would invalidate the position's thesis. Use this whenever the user asks "how's my position", "am I in trouble", "how far am I from liquidation", "should I hold or close", "what do you think of my long / short", or pastes a position. It reports and explains; it never tells the user to close, add, hedge or move a stop, and it cannot trade.
---

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.

## 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"]`, and the coins as `symbols` (up to three in ONE call; each
   coin's read is its own entry in `data[]`). 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 ≈ 1 + 1 (+3) calls. If the quota is tight, skip step 3: technicals and
derivatives for every position are still two calls.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: smart-money
description: Track what top crypto futures traders — "smart money", whales, elite accounts — are doing across Binance, Hyperliquid, Bybit and OKX with TraderSpy's live tracking data. The elite leaderboard by smart score, top traders by ROI or PnL over 24h to 30d, open and closed positions filtered by coin, exchange or trader, one trader's profile and closed-trade history, and aggregate market stats. Use this whenever the user asks what whales or top traders are buying, shorting or holding, who the best traders are on an exchange, whether big accounts are long or short a coin, wants to research a trader's record before acting on it, or says "smart money", "whale watch", "what are the pros doing". Not for funding rate / open interest / long-short ratios of the whole market (technical-analysis) and not for AI signals (trading-signals).
---

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.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: technical-analysis
description: Read one crypto futures pair (or a few) properly with TraderSpy — 19 indicators (RSI, MACD, EMA/SMA stacks, Bollinger, ATR, ADX, Stochastic, OBV, VWAP, CCI, MFI, Williams %R, ROC, SuperTrend, Ichimoku, Keltner), pivot points and swing support/resistance, Fibonacci and volume profile, RSI/MACD divergence, squeezes and candle patterns, up to three timeframes and up to three coins in ONE call with a confluence verdict — plus funding rate, open interest and long/short positioning, live price and OHLCV candles. Use this whenever the user asks about a coin's chart, trend, momentum, "is X overbought / oversold", support and resistance, where the 200 EMA is, "analyse BTC", "how does SOL look", "what do the indicators say", "is this a good entry", whether funding is high or open interest is building, or wants price / candle data — even if they only name a coin and ask how it looks. For scanning MANY coins by conditions use market-screener; for whale positions use smart-money.
---

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.

## Tools

| Tool | Use it for | Key arguments |
| --- | --- | --- |
| `get_technical_indicators` | The chart read | `symbol` or `symbols` (≤ 3), `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.
- **Several coins are one quota unit too.** "How do BTC, ETH and SOL look" or a deeper read of a
  screen's top matches → `symbols: ["BTCUSDT","ETHUSDT","SOLUSDT"]` in ONE call, with the same
  `intervals` and `indicators` for all of them — never one call per coin. Up to three coins per
  call; for more, one call per three. For a quick side-by-side of many coins on one timeframe,
  `screen_symbols` (market-screener) is the better tool.
- **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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: trading-signals
description: Query, explain and evaluate TraderSpy's AI crypto futures signals — the newest signals, signals for one coin, what a signal's entry / take-profit / stop levels and triggered conditions mean, whether a signal still stands at the current price, and how signals have performed (hit rate, hits vs stops) over the last 4h to 7d. Use this whenever the user mentions crypto signals, AI alerts, "any setups", "what is the AI seeing", long/short ideas, TraderSpy alerts, signal performance or track record — even when they never say the word "signal". Not for placing trades (no tool can), not for whale or top-trader positioning (smart-money), not for indicator reads on a coin (technical-analysis).
---

TraderSpy's AI signals are automated reads of the market: a named preset fires when several
technical conditions line up on one crypto futures pair, a validator scores the alignment, and
the published signal carries an entry, a take-profit ladder, a stop and — later — what actually
happened. The signals feed at https://traderspy.app/signals publishes every one with its resolved
outcome. Your job is to fetch,
translate and contextualise them; the decision stays with the user.

## Tools

| Tool | Use it for | Key arguments |
| --- | --- | --- |
| `get_signals` | The list: newest first | `limit` 1–50 (default 20), `skip`, `importance` high / medium / low / all, `coin` |
| `get_signal_details` | One signal in full, plus the live price | `signalId` (the `id` from the list) |
| `get_signal_stats` | Aggregate hit rate over a window | `period` 4h / 8h / 24h / 7d |

Three argument behaviours that are easy to get wrong:

- **`importance` is inclusive downward.** `high` returns high only, `medium` returns high AND
  medium, `low` returns everything. To show "medium and above" pass `medium`, not `low`.
- **`coin` is a prefix match** on the pair name. `BTC` matches `BTCUSDT` and also `BTCDOMUSDT`;
  check the `coin` field of each row before presenting "BTC signals".
- **`limit` is what gets rendered.** In hosts that draw signal cards, every fetched row becomes a
  card. If the user asks for "the last 5", pass `limit: 5` — do not fetch 20 and show 5.

## What a signal row contains

`strategyName` (the preset, e.g. "OBV Divergence Buy (4H)") · `action` buy / sell · `timeframe`
1h / 4h / 1d · `price` at trigger · `targets[]` as `{label, type, pct}` where `pct` is measured from
`price` · `triggeredConditions[]` in plain language · `importance` · `signalStrength` weak /
moderate / strong / very_strong · `resolutionStatus` · `createdAt`.

Convert target percentages to prices before showing them — users think in prices:

- buy: TP = price × (1 + pct/100), SL = price × (1 − pct/100)
- sell: TP = price × (1 − pct/100), SL = price × (1 + pct/100)
- reward-to-risk at TP1 = TP1 pct ÷ SL pct (a 0.7 R:R is normal for this system, whose first target
  sits close to entry; read it together with the hit rate from `get_signal_stats`, and do not call a
  sub-1 R:R "bad" on its own).

`resolutionStatus` is the outcome so far:

| Status | Meaning |
| --- | --- |
| `pending` | Still inside its tracking window, nothing hit yet |
| `tp1_hit` / `tp2_hit` / `tp3_hit` | Highest take-profit reached (a later stop touch does not downgrade it) |
| `profit_locked` | Trend exhaustion detected before TP1; a partial gain was locked |
| `stop` | Stop level touched before any take-profit |
| `expired` | Window ended with neither side touched |

Outcomes are judged on 1-minute wicks, so "TP1 hit" means price actually traded there. The
tracking window is 24 × the signal timeframe (24h for a 1h signal, 4 days for a 4h signal); a 1h
signal that is still `pending` two days later is stale rather than alive.

## Workflows

**"Latest signals" / "any setups?"** → `get_signals` with the limit the user implies (default 10 if
they gave no number). Lead with the newest, group by side if several, and make the resolved ones
visible — a list that mixes three winners, tw

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.