# TraderMatrix > TraderMatrix (www.tradermatrix.pro, formerly TraderDaddy Pro) is an options-flow and market-intelligence platform for retail options and stock traders. It shows where large options orders, dealer gamma and institutional money are positioned — unusual options activity, gamma exposure (GEX) and Apex levels, dark-pool rollups, sector flow, signal scanners and screeners — alongside a wheel-strategy tracker, a trade journal with broker sync, and Arya, an AI trading assistant. The same data is available to AI assistants through a REST API and an MCP server. ## About the platform (for people asking "what is TraderMatrix?") - **What it is:** a web platform (desktop + installable mobile PWA) that turns options-market positioning into trade ideas and levels. Core question it answers: *where is the smart money and the dealer hedging pressure, and what does that mean for this ticker today?* - **Who it's for:** self-directed options traders — day traders, swing traders, wheel/income sellers and long-term investors — who want institutional-style flow and gamma tools without paying for several separate subscriptions. - **Pricing:** a free account (limited previews of most tools, several free tools) and one paid plan, **TraderMatrix Premium at $49.99/month**, which unlocks everything. Current plan details: https://www.tradermatrix.pro/pricing . The Developer API/MCP server is a separate add-on (see below). - **Tool pillars** (full catalog: https://www.tradermatrix.pro/features): - **Options Flow** — unusual activity scoring, live flow, heat map, sector flow, earnings flow, dark-pool rollups. - **Signal Scanners** — breakouts, triangle breakouts, bounce finder, gap continuation, Apex Magnet scanner. - **Options Screeners** — cash-secured put / wheel, momentum and other preset screeners. - **Research** — ticker search with per-ticker flow, GEX, Apex levels and Ticker Lab (options strategy lab). - **Smart Tools** — wheel tracker, trade journal, options calculator, watchlists. - **Markets & Smart Money** — market health regime, GEX for SPX/ES/NQ/SPY/QQQ, congressional (politician) trades, insider activity, ETF tracker. - **Calendars & Intel** — earnings, economic calendar, dividends, IPO scanner, news wire. - **AI & Automation** — Arya AI assistant (in-app chat + Discord), alerts, the MCP server. - **What makes it different:** derived signals rather than raw tape (each unusual options print is scored 0–100 on volume-to-open-interest, premium size and bid-ask execution); gamma-based Apex levels that show where dealer hedging pins or accelerates price; one subscription instead of separate flow, GEX, wheel-tracking and journal tools; and a first-party MCP server so the platform's analysis works inside Claude, Cursor and other AI assistants. - **Free learning content:** https://www.tradermatrix.pro/learn — plain-English guides to every tool, options concepts (GEX, gamma flip, IV rank, unusual activity) and personal-finance topics. - **Glossary of options terms:** https://www.tradermatrix.pro/glossary - **Comparisons with other tools:** https://www.tradermatrix.pro/compare - **Every public page, described:** https://www.tradermatrix.pro/llms-pages.txt (both files in one fetch: https://www.tradermatrix.pro/llms-full.txt) - **Community:** Discord https://discord.gg/apexhunters · X https://x.com/TraderMatrixHQ · YouTube https://www.youtube.com/@TraderMatrixHQ Not financial advice: TraderMatrix provides market data analysis and education, not personalized investment recommendations. --- ## Developer API & MCP Server > TraderMatrix is an options-flow and market-intelligence platform. The Developer API is a paid REST + MCP (Model Context Protocol) surface that lets you pull the same institutional options flow, gamma exposure (GEX), unusual activity, screeners, sector rotation, congressional trades, earnings flow, and long-term/dividend data your subscribers see — directly into your own tools or into an AI assistant (Claude Desktop, Claude Code, Cursor, Gemini CLI, Codex). > > This file is a complete, LLM-friendly reference. Human docs: https://www.tradermatrix.pro/developers New to this? Read the **Quick Start for beginners** section first. It walks you from "I just installed Claude and paid for the add-on" to "my AI can pull live market data" in a few minutes — no coding required. Want the overview of what an AI can read through TraderMatrix, with example questions and plans? See https://www.tradermatrix.pro/arm-your-ai Never edited a config file before? There is a fully spelled-out, click-by-click version of that same setup at https://www.tradermatrix.pro/learn/mcp-setup — where the key lives, one numbered path per app, and what a working connection looks like. --- ## What you get - **REST API** — 30+ HTTPS endpoints returning JSON. Good for scripts, dashboards, alerts, spreadsheets, automations. - **MCP server** — one endpoint that plugs TraderMatrix into an AI assistant so you can just *ask* for the data in plain English ("what's the unusual options flow on AAPL today?", "which dividend stocks go ex-div this week?"). - Both use the **same API key** and share the **same 30-requests/minute** limit. - Market data is **read-only**. The API cannot place trades or move money. The one thing it can change is your own watchlists — the MCP watchlist tools add, remove and organize tickers on the account that owns the key. ## Who it's for - Traders who want live flow/GEX/screener data inside Claude, Cursor, Gemini CLI, Codex, or their own scripts. - People automating research for a strategy — e.g. wheel-strategy monitoring, DCA timing, dividend-capture, earnings positioning. (See the **Example: wheel & dividend workflow** section.) - Developers building trading tools, alerts, or dashboards on top of TraderMatrix data. --- ## Getting access (pricing & steps) The Developer API is a **standalone product**. It does NOT require a Premium trading subscription -- a free account can subscribe to it directly. 1. **Create a free account** — https://www.tradermatrix.pro/register 2. **Subscribe to the Developer API** — **$49.99/mo standalone**, or **$29.99/mo** while you also hold a TraderMatrix subscription. Billed separately from the platform. If you cancel the platform subscription later, the API moves to $49.99/mo from its next invoice. In the app: **Settings → Developer tab** (https://www.tradermatrix.pro/settings?tab=developer). 3. **Generate an API key** — on the Developer tab, click "Generate API Key". Keys are prefixed `td_live_`. **The full key is shown only once** — copy it somewhere safe (a password manager). You can hold up to **5 active keys** and revoke any of them anytime. 4. **Start using it** — either paste the key into your AI assistant's MCP config (below) or send it as a header in REST calls. The **MCP server is included** with API access — no separate purchase. ### Access tiers (MCP) Any logged-in account can generate a key (Settings → Developer) and connect to the MCP endpoint (`POST /api/v1/mcp`). What the key can do depends on the account: - **Free account — preview.** 25 MCP tool calls per UTC day. Every list in a result is cut to its first 3 items and the result carries a `preview` field (`shown`, `total`, `message`, `upgradeUrl`). Tools that return third-party news/calendar/quote-style data and the watchlist write tools answer "Premium feature". `tools/list` still lists every tool. - **TraderMatrix Premium.** MCP access with full results, 200 tool calls per UTC day. REST (`/api/v1/*`) is not included. - **Developer API add-on.** REST + MCP, the per-minute limits above, no daily cap. Free and Premium MCP keys are also limited to **12 tool calls per minute per account** (across all of the account's keys), and at very busy moments a tool may answer "TraderMatrix is busy right now" — wait a minute and retry. Repeated identical questions are served from a short shared cache. The 30/min per-key figure above is the Developer API add-on's limit. Past a daily limit the tool returns an error saying so, with the upgrade link. In short: free accounts get a 25-call/day preview; Premium members get MCP access (200 tool calls/day); the Developer API add-on unlocks REST + higher limits. --- ## Authentication - **Base URL:** `https://api.tradermatrix.pro/api/v1` - **Legacy hostname:** `api.traderdaddy.pro` (the pre-rebrand name) is the same server and keeps working permanently — existing configs and scripts need no change. - **REST auth:** send your key in the `X-API-Key` header on every request. - **MCP auth:** send your key as `Authorization: Bearer td_live_...` (the `X-API-Key` header also works). ```bash curl -H "X-API-Key: td_live_your_key_here" \ "https://api.tradermatrix.pro/api/v1/unusual-activity?minScore=85&timeFrame=today" ``` Keys are never exposed to the browser and are hashed at rest — only a short prefix is stored in clear. Treat your `td_live_` key like a password. ## Rate limits - **30 requests per minute per key** (REST calls and MCP tool calls both count against this). - Every response includes: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix timestamp when the window resets). - Exceed it and you get `HTTP 429`; wait until `X-RateLimit-Reset` and retry. ## Error handling Errors return JSON: `{ "error": "...", "message": "..." }`. | Status | Meaning | |---|---| | 200 | OK — data in the response body | | 400 | Bad request — missing/invalid query parameters | | 401 | Unauthorized — API key missing or malformed (`td_live_` prefix required) | | 403 | Forbidden — key doesn't have permission / API access inactive | | 429 | Rate limit exceeded — retry after `X-RateLimit-Reset` | | 500 | Server error — contact support if it persists | --- ## Quick Start for beginners — connect Claude to TraderMatrix (no code) This is the fastest path if your goal is "let my AI assistant read live market data." You only need your `td_live_` key. ### Claude Desktop (the Claude app) Claude Desktop can't call a remote HTTP server directly, so it bridges through a small helper called `mcp-remote` (this needs **Node.js** installed — get it from https://nodejs.org). Open Claude Desktop → **Settings → Developer → Edit Config**, and add this to `claude_desktop_config.json`: ```json { "mcpServers": { "tradermatrix": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.tradermatrix.pro/api/v1/mcp", "--header", "Authorization: Bearer td_live_your_key_here" ] } } } ``` Replace `td_live_your_key_here` with your real key, save, and **fully restart Claude Desktop**. You'll see a tools/plug icon appear. Now just ask: *"Using TraderMatrix, show me today's unusual options activity with a score above 85."* ### Claude Code (the CLI) Run this one command (swap in your key): ```bash claude mcp add --transport http tradermatrix \ https://api.tradermatrix.pro/api/v1/mcp \ --header "Authorization: Bearer td_live_your_key_here" ``` Then start `claude` and ask for market data directly. ### Cursor Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "tradermatrix": { "type": "http", "url": "https://api.tradermatrix.pro/api/v1/mcp", "headers": { "Authorization": "Bearer td_live_your_key_here" } } } } ``` ### Gemini CLI One command (swap in your key): ```bash gemini mcp add --transport http \ --header "Authorization: Bearer td_live_your_key_here" \ tradermatrix https://api.tradermatrix.pro/api/v1/mcp ``` Or add it by hand to `~/.gemini/settings.json`. Use **`httpUrl`**, not `url` — in Gemini CLI `url` means SSE, which this endpoint does not serve, and the server never connects: ```json { "mcpServers": { "tradermatrix": { "httpUrl": "https://api.tradermatrix.pro/api/v1/mcp", "headers": { "Authorization": "Bearer td_live_your_key_here" } } } } ``` Run `/mcp` inside `gemini` to confirm the tools loaded. ### Codex (OpenAI's CLI) Codex reads the key from an environment variable, so it never sits in a config file. Set the variable in the shell you start `codex` from (add it to your shell profile to keep it): ```bash export TRADERMATRIX_API_KEY=td_live_your_key_here codex mcp add tradermatrix \ --url https://api.tradermatrix.pro/api/v1/mcp \ --bearer-token-env-var TRADERMATRIX_API_KEY ``` Or add it by hand to `~/.codex/config.toml`: ```toml [mcp_servers.tradermatrix] url = "https://api.tradermatrix.pro/api/v1/mcp" bearer_token_env_var = "TRADERMATRIX_API_KEY" ``` `bearer_token_env_var` takes the variable's **name** — put your `td_live_` key in the variable, not in this line. ### Browser-based clients (TradingView AI Chart Copilot and similar) Some MCP clients run inside the browser — notably AI Chart Copilot, the Chrome extension that adds an AI side panel to TradingView charts. These let you attach your own MCP server, which puts TD Pro's dealer gamma, unusual flow and apex levels next to the chart you're already reading. In the client's MCP-server settings, add a server with: - **URL:** `https://api.tradermatrix.pro/api/v1/mcp` - **Auth:** either a header — `Authorization: Bearer td_live_your_key_here` (or `X-API-Key: td_live_your_key_here`) — or **OAuth**, if the client offers it. With OAuth you paste your key once on our consent page instead of storing it in the client's config. Both paths land on the same tools (the full list is below) and the same 30/min limit. Once connected, you don't write code — you ask. The assistant picks the right tool, calls it with your key, and explains the result. Tool calls count against your 30/min limit. --- ## MCP tools (50 tools — 43 read-only market-data tools + 7 for your own watchlists) Ask your assistant for any of these in plain English; it maps your question to the right tool. Every tool result carries an `openInTraderMatrix` field (a `url` and `label`) that deep-links to the matching TraderMatrix page. The server also publishes MCP prompts that show up as slash commands in clients that support them: `morning_briefing`, `wheel_candidate_check`, `ticker_deep_dive`, `market_regime_today` and `unusual_flow_scan`. **Market & sentiment** - `get_market_stats` — SPY/QQQ/IWM put/call ratios and sentiment, plus the largest unusual options trade for the current trading date. For overall market health/breadth, use `get_market_health` instead. - `get_macro_regime` — Macro regime from Treasury, Federal Reserve, FRED and CFTC series: yield curve and 10Y-2Y spread, 10Y real yield, breakeven, 5Y5Y forward inflation, fed funds, Fed net liquidity, and CFTC E-mini S&P 500 positioning. Units and asOf on every field, plus an interpretation sentence. - `get_market_internals` — Derived market internals: S&P 500 breadth (percent above 20/50/200-day averages, advancers/decliners, net new 52-week highs, zones), 60-session stock/bond and dollar/equity correlations, cross-asset ratios (VIX/VIX3M term structure, gold, copper-to-gold, oil 20-session changes) and the equity-risk-premium zone with implied ERP. Percent, ratios and correlations only — no index, futures or volatility levels, no fair-value prices. - `get_market_health` — 9 macro-regime detectors (risk appetite, credit, breadth, volatility, financial conditions, rotation) rolled into one read. Each signal carries its status plus derived detail only (ratios, percent vs moving average, N-day changes — never raw prices); the composite score is in points with its cutoffs. - `get_market_health_history` — the composite risk score's last 30 days of snapshots (with label flips in the last 7 days), a ~30-session derived line series per detector (percent vs moving average, ratios vs their MAs, N-day percent changes and spreads, each with a unit), and which scored detectors changed status since the previous trading day. The junk-credit-spread detector has no lines (its source series is third-party licensed) and economic-calendar events are not included. - `get_market_valuation` — S&P 500 valuation verdict (Very cheap / Cheap / Fair value / Rich / Very rich) from a discounted-earnings equity-risk-premium model: the premium the market currently implies (`impliedErpPct`, percent — lower means richer), how far the market sits above or below the Fair value band, and five ERP bands. Percentages only — index-point fair values, the index level and the earnings inputs are not published. A model, not a forecast. - `get_macro_liquidity` — US-government macro and liquidity series: Fed net liquidity (USD trillions, 4-week change), 10-year real yield, breakeven inflation, 5y5y forward inflation, effective fed funds rate, the Treasury yield curve and 10Y-2Y spread history, private nonresidential fixed investment (CAPEX), and CFTC E-mini S&P 500 positioning by trader class. Third-party-licensed credit-spread series are not included. - `get_cross_asset_regime` — derived cross-asset read: 60-session stock-bond and dollar-stock correlations, 20-session percent changes of the gold/S&P ratio, copper/gold ratio and WTI crude, the VIX/VIX3M ratio with a contango/backwardation word, and the MOVE/VIX ratio. No raw index or commodity levels; an uncomputable leg is `null` and named in `unavailable`. - `get_market_breadth` — Derived S&P 500 breadth — percent of members above their 20/50/200-day averages, advancers/decliners, net new 52-week highs, breadth zones and a one-sentence read. Aggregates only: no index level or index change. - `get_put_call_ratios` — put/call ratio for one ticker you name, from its nearest weekly expiration (open-interest fallback when intraday volume is thin). `putCallRatio` and `sentiment` are both `null` when there is no call volume to divide by. - `get_conviction` — Community Conviction gauge (0–100 blend of how TD Pro traders lean on a ticker). **Options flow** - `get_unusual_activity` — real-time unusual options activity with scoring and sentiment. - `get_institutional_activity` — most active tickers by institutional options-flow volume today, with directional bias. - `get_directional_flow` — the session's cumulative (from-open) delta-weighted flow lean per underlying (cumΔ, conviction, bullish/bearish/balanced bias); pass a symbol or get the top-15 leaderboard. - `get_dark_pool` — rolled-up off-exchange ("dark pool") equity BLOCK flow for a ticker: print count, gross and net notional, accumulation vs distribution split, largest print. The lean is inferred, not confirmed direction — it describes months of desk positioning, so distribution means a patient seller (stalling/sideways), not a short signal. Aggregates only — individual prints are not served. - `get_gap_continuation` — Gap Continuation Scanner: large-cap names that gapped 2%+ and then broke the opening range in the SAME direction, graded A to D by how many of three checks agree (GEX regime, options flow, sector flow). Returns ticker, direction, grade, a coarse gap bucket (the exact gap size is not published), which confirmations agree, and whether it is an earnings gap. sessionDate names the ET trading day shown: before the open, on weekends and on holidays that is the last session that produced any. - `get_breakout_signals` — Breaking Out scanner: active daily breakout and continuation signals, newest first. Ticker, signal type, direction, price at detection, stop/target (null if they would sit on the wrong side of entry), detectedAt. Filter by ticker, direction, `since` (ISO timestamp, for polling new signals), limit. - `get_breakout_tape_confirmed` — Breakout + Tape Confirmed: Breaking Out names the live options tape is ALSO buying bullish this session. Ticker, conviction (0..1), firstSeenAt, relative strength vs SPY (percent), gamma regime. Derived verdicts only; empty outside the session. - `get_sector_flow` — options flow aggregated by GICS sector ETF with sentiment breakdown. - `get_earnings_flow` — pre-earnings unusual positioning for tickers reporting soon. **Start here for a ticker** - `get_ticker_snapshot` — One-call derived snapshot of a ticker — quality score and label, gamma regime and spot-vs-flip relation, nearest Apex level, session flow bias and conviction, IV rank (out of 100, with zone and interpretation) and the Market Health headline. Each section settles independently; derived scores only, no quotes, volume, open interest, fundamentals or news. **Gamma exposure (GEX) & levels** - `get_gex_overview` — gamma exposure across tracked symbols, flip points, key walls. - `get_gex_ticker` — gamma exposure for any single ticker; also flags a `gammaPocket` (positive/negative) when the name's dealer gamma diverges from the broad-market regime. - `get_apex_levels` — composite "magnet" strike ranking (OI walls + net gamma) with the gamma-flip level. **Volatility & structures** - `get_iv_rank` — self-relative IV rank (is a ticker's premium rich or cheap vs its own history?). Every reading carries a `source`; `ivPercentile` is present only on a `self_tracked` reading. - `get_strategy_ideas` — ranked, auto-assembled multi-leg option structures priced off the live chain. - `get_edge_xray` — whole-chain rich/cheap grade for one expiration, with an optional trade-archetype lens. - `get_hedge_analysis` — ranked downside-protection structures (collars, puts, spreads) for a share position you specify. **Screeners & signals** - `run_screener` — run a named screener at defaults (bullish-pullback, momentum, volatility-squeeze, small-cap, volatility-surge, gamma-scan, csp-wheel, leaps, leveraged, daily-cuts, accumulation-watch). If the screener's data source is down it returns a tool error ("temporarily unavailable") rather than an empty list. - `get_bounce_signals` — Bounce Finder: recently detected oversold-bounce candidates with scoring. - `get_bounce_score` — on-demand oversold-bounce composite score for one ticker. - `get_premarket_gappers` — 5-pillar momentum gap scan (gap >=10%, price $1-$100, float <=100M, premarket volume >=50k; relative volume ranks the board and news is flagged). A common day-trading screen pattern; independent implementation, not affiliated with or endorsed by Warrior Trading or Ross Cameron. Runnable on the pre-market or after-hours tape. `rvol` is DERIVED — premarket volume ÷ 10-day average FULL-day volume, i.e. what fraction of a normal day has already traded. It is NOT TradingView's regular-session relative volume, which is meaningless before the bell. The news pillar is served as a boolean `hasNews` only; headline text, source, and article links are not redistributed. **Intelligence, events & long-term** - `get_politician_trades` — congressional "Power Players" most-active disclosure leaderboard. - `get_politician_trades_by_ticker` — every congressional disclosure trade for a single ticker. - `get_insider_trades` — Form 4 insider trades of $25k+ filed with the SEC over the past 21 days, market-wide or filtered to one ticker. Every row carries a `direction` (`buy`/`sell`/`other`); the `direction` param defaults to `buy`, pass `sell`, `other` or `all` for the other sides (`other` is awards, gifts and tax withholding — not trades in either direction). Every response also carries `available` — `{buy, sell, other}` counts for the whole 21-day window before the filter, so `count: 0` on a `buy` query is distinguishable from no insider activity at all. - `get_short_interest` — official FINRA short data for a ticker: bi-monthly short interest (days-to-cover, current short position) plus the latest daily Reg SHO short-volume ratio (short activity is squeeze/positioning context, NOT a bearish signal). - `get_economic_calendar` — macro events (FOMC, CPI, NFP) with consensus estimates and, once a report prints, its actual value (from FRED's official agency releases). - `get_long_term_quality` — fundamental quality + dividend screener across the optionable universe. - `get_dividend_calendar` — upcoming ex-dividend calendar with yields and pay dates. - `get_ipo_scanner` — the pipeline from pre-IPO chatter to freshly-listed names. - `get_ticker_news` — catalyst news for one ticker: the single most decision-relevant recent headline (`topCatalyst`), a count of hard catalysts in the recency window, and recent categorized supporting headlines with source and link. Answers "why is $X moving?". Routine market commentary and "mover" wrappers are filtered out; when only commentary exists `topCatalyst` is null rather than invented. - `get_crypto_quote` — live USD spot for named coins (BTC, ETH, SOL, and any other by ticker): price, 1h/24h/7d/30d change, market cap, 24h volume, circulating/max supply, rank, and the source's own `lastUpdated` (null means it did not say — never our clock). Also returns `notFound` for symbols with no quote, so a missing coin is visible rather than silently dropped. Max 10 symbols per call; a longer list is rejected, not truncated. - `get_crypto_market_overview` — the market-wide crypto read: total market cap and its 24h change, total 24h volume, BTC and ETH dominance, active-currency count, and the largest coins by market cap. Read dominance as rotation, never as a price target. **Your watchlists** (the account that owns the API key — there is no way to name another account) - `list_watchlists` — every one of your lists with its tickers and notes, plus your list and ticker limits. Call it first when you refer to a list by name. - `add_to_watchlist` — add a ticker (optional note) to a named list, or your default list. Re-adding a ticker that's already there just updates its note. - `remove_from_watchlist` — remove a ticker from one named list, or from every list it's on. - `move_watchlist_ticker` — move a ticker between lists; the destination list's ticker cap applies. - `create_watchlist` — create a new named list (free accounts get one list, paid up to 12). - `update_watchlist` — rename a list, change its category, or make it your default. - `delete_watchlist` — delete a list and every ticker on it; your default list can't be deleted. > Crypto is **spot only**. There is no options chain, gamma exposure, unusual flow, apex level or dark-pool data for any coin — every other tool on this server covers US equities and equity options. --- ## REST endpoint reference All paths are relative to `https://api.tradermatrix.pro/api/v1`. All require the `X-API-Key` header. ### Options Flow - `GET /unusual-activity` — real-time unusual options activity with scoring and sentiment. - Params: `timeFrame` (hour|today|todayOrLastSession|yesterday|3days|week|month, default today; `todayOrLastSession` serves the last complete session until the market opens), `type` (SWEEP|BLOCK|SPLIT|GOLDEN_SWEEP), `sentiment` (BULLISH|BEARISH|NEUTRAL), `ticker`, `minPremium` (dollars), `minScore` (0–100), `page` (default 1), `pageSize` (max 100, default 10). - Response carries `sessionDate` (`YYYY-MM-DD`, ET): the trading session the rows were read from for `today` / `todayOrLastSession` / `yesterday`; `null` for rolling windows. - `GET /unusual-activity/stats` — aggregate counts/sentiment breakdown for the current unusual-activity window. - `GET /unusual-activity/repeats` — tickers with repeated opening flow in a rolling window. Param `hours` (1-72; out of range returns HTTP 400, it is not clamped). - `GET /unusual-activity/repeats/:ticker` — repeat-flow detail for one ticker. - `GET /unusual-activity/:id/translate` — plain-English translation of one flow row (what the trade means, not just its raw fields). - **Freshness:** the feed response caches 45–60s at the API layer, but new rows come from a tiered background scan that only ticks every 5 minutes during market hours — nothing can be fresher than that. Within each tick, tickers are rescanned on their own cadence: Tier 1 (core indices/mega-caps) every 5 min, Tier 4/Reddit-trending every 17 min, Tier 2 (institutional favorites) every 13 min, Tier 3 (curated watchlist) every 30 min. With a narrow filter (e.g. `minPremium`), repeated identical results usually mean nothing new has qualified in that ticker's scan window yet, not a delivery delay. Results are ordered `detected_at` DESC (newest first), `unusual_score` DESC as tiebreaker. - `GET /flow/summary` — top tickers ranked by net premium and volume. - Params: `days` (0=today, 1–30, default 3), `minPremium` (default 20000), `limit` (max 500, default 50), `tickers` (comma-separated). - `GET /flow/ticker/:ticker` — flow summary scoped to one ticker. - Dark pool (off-exchange block flow): use the `get_dark_pool` MCP tool above — it returns window aggregates, not a per-print tape. Platform page: `/dark-pool` (Premium; 50 most liquid tracked names). No standalone REST endpoint in the public API. ### Market Data - `GET /market-pulse` — AI-generated market sentiment narrative, updated through the session. - `GET /market-pulse/thermal` — per-ticker technical read (RSI, Stochastic, Williams %R, MACD, ADX, CCI, Bollinger %B, EMA21 distance) for SPY/QQQ/IWM/GLD/IBIT plus VIX. Not breadth: no advancers/decliners, no volume thrust. - `GET /market-pulse/vix` — VIX level only: value, change, change percent. No term structure. - `GET /market-stats` — index put/call ratios, sentiment, market-health metrics. - `GET /put-call-ratios` — put/call ratios for SPY, QQQ and IWM from each one's nearest weekly expiration. `putCallRatio` and `sentiment` are both `null` when there is no call volume to divide by. - `GET /put-call-ratios/:ticker` — the same read for any other symbol, from its nearest weekly expiration. ### Market Health - `GET /market-health` — the composite risk score (points, with LOW/ELEVATED/HIGH cutoffs) and every detector's status, summary and derived detail. Same payload as the `get_market_health` MCP tool. - `GET /market-health/history` — 30 days of composite snapshots, ~30-session derived line series per detector, and status changes since the previous trading day. Same payload as `get_market_health_history`. - `GET /market-health/valuation` — S&P 500 equity-risk-premium valuation verdict and bands, as percentages only. Same payload as `get_market_valuation`. - `GET /market-health/macro` — US-government macro and liquidity series: Fed net liquidity, real yield, breakevens, fed funds, Treasury yield curve and 10Y-2Y spread, CAPEX, CFTC E-mini S&P 500 positioning. Same payload as `get_macro_liquidity`. - `GET /market-health/cross-asset` — derived cross-asset correlations, ratio changes and VIX/VIX3M term structure. Same payload as `get_cross_asset_regime`. - `GET /market-health/breadth` — S&P 500 breadth aggregates (percentages and counts only). Same payload as `get_market_breadth`. > Derived values only: no raw index, ETF or commodity levels, no third-party-licensed credit-spread series, and no economic-calendar rows. A leg that cannot be computed is `null`/omitted and named in `unavailable`; a failed upstream returns `502`. ### Scans - `GET /scans/breakout-tape-confirmed` — Breaking Out names the live options tape is ALSO buying bullish. Per row: `ticker`, `direction`, `conviction` (0..1), `firstSeenAt`, `rsVsSpyPercent`, `gammaRegime`. Derived verdicts only; no option rows or quotes. Empty outside the session. Same payload as `get_breakout_tape_confirmed`. New Breaking Out signals themselves are on `GET /signals` (poll it) and the `get_breakout_signals` tool. ### Gamma Exposure (GEX) - `GET /gex/market/overview` — GEX for tracked index symbols (SPX, SPY, QQQ) with flip points and walls. - `GET /gex/:symbol` — GEX analysis for any ticker (computed on-demand for non-tracked symbols). - `GET /gex/:symbol/historical` — historical GEX time series (tracked symbols only: indices, sector ETFs, GLD/SLV, and 7 mega-caps). - `GET /gex/:symbol/matrix` — GEX/VEX matrix (dealer positioning) by strike and expiration. - `GET /gex/:symbol/apex` — Apex Levels: proximity-weighted OI walls + net gamma scored 0–100, with the gamma-flip level. Optional `expiration` (YYYY-MM-DD). - `GET /gex/:symbol/apex/trend` — multi-day Apex trend, one point per trading day. Param `days` (1–90, default 30). - `GET /gex/:symbol/apex/history` — intraday Apex history for the current session plus previous close. - `GET /gex/:symbol/apex/evolution` — how the Apex magnet level has shifted expiration-over-expiration. - **Freshness:** `/gex/:symbol/matrix`, `/gex/:symbol/apex`, and `/gex/:symbol/apex/evolution` are computed on-demand and cached per symbol — 15 min during regular market hours (9:30am–4:00pm ET), 6h off-hours on weekdays, 24h on weekends/holidays. It's a rolling window from the last computed value, not clock-aligned, so a served snapshot can be anywhere from a few seconds to just under that window old. `/gex/:symbol/apex` returns a `freshness` object (`computedAt`, `ageSeconds`, `refreshSeconds`, `stale`); `/gex/:symbol/matrix` doesn't, but check `data.snapshotTime` directly there. `/gex/:symbol/apex/evolution` has neither `freshness` nor `snapshotTime` in its response today — there's currently no way to check its age client-side. `/apex/history` (60s cache, ~10-min snapshot cadence) and `/apex/trend` (5-min cache, daily granularity) are separate, slower-moving series built from stored snapshots rather than a live chain calc. The website reads the same cache as this API — there's no faster tier by subscription level. ### Sector Analysis - `GET /sectors/flow` — options flow aggregated by GICS sector ETF (net premium, sentiment, top tickers). Param `window` (1h|4h|1d|1w, default 1d). - `GET /sectors/heatmap` — sector heatmap visualization data. Param `window` (1h|4h|1d|1w, default 1d). - `GET /sectors/etfs` — the sector→ETF symbol mapping. - `GET /sectors/analysis` — sector ETF performance + oscillator/volume technical state. - `GET /sectors/dashboard` — macro hero + sector grid + technicals in one payload. Param `window` (today|5d|1m, default today). - `GET /sectors/rotation` — RRG-style sector rotation map vs SPY. Param `trail` (5|10|20|40 sessions, default 10). - `GET /sectors/market-map` — per-ticker options-flow bubble canvas (top ≤60 tickers by premium). Param `window` (today|5d|1m, default today). - `GET /sectors/:etf/flows` — drill-down: every flow that contributed to a sector's net activity (e.g. XLK, XLF, XLE). ### Signals & Scanners - `GET /signals` — technical breakout/continuation signals. Params: `type` (BREAKOUT|CONTINUATION), `ticker`. - `GET /signals/stats` — aggregate signal counts/hit-rate stats. - `GET /signals/:id` — detail for one signal. - `GET /signals/:id/chart-data` — chart series backing one signal. - `GET /bounce-finder` — reversal-finder signals from a 9-component composite score. - `GET /screeners` — list all available screeners with their parameter schema. - `GET /screeners/:id` — detail (params, defaults, fixed criteria) for one screener. - `GET /screeners/:id/run` — run a named screener with query-string params. `id`: bullish-pullback | momentum | volatility-squeeze | small-cap | volatility-surge | gamma-scan | csp-wheel | leaps | leveraged | daily-cuts | accumulation-watch | stage2-uptrend | momentum-leaders. `stage2-uptrend` and `momentum-leaders`: membership list only on the public API (symbol, name, direction, earningsSoon; no prices or market data). - `POST /screeners/:id/run` — same as above but params go in a JSON body — the only endpoint on this API shaped that way. Both run routes answer **503** `{ error: "Screener unavailable", message }` when the screener's data source fails (an outage, not "nothing matched" — an empty match is a 200 with empty `results`; retry shortly), and **429** `{ error, message, retryAfter }` when you exceed the per-account screener-run limit. ### Earnings & Events - `GET /earnings` — earnings calendar with expected-move estimates. Params: `week` (true=this week), `date_from`, `date_to` (YYYY-MM-DD). - `GET /earnings-flow/flow` — pre-earnings unusual positioning. Params: `days`, `minFlows`. - `GET /earnings-flow/flow/:symbol` — pre-earnings positioning for one ticker. - `GET /economic-calendar` — macro events (FOMC, CPI, NFP) with consensus estimates and, once a report prints, its actual value (from FRED's official agency releases). - `GET /economic-calendar/predictions` — market-implied odds for high-impact events (Kalshi-sourced). ### Intelligence - `GET /politician-trades` — congressional STOCK Act disclosures, sourced from the House Clerk and Senate eFD. Params: `window` (days, default 90), `limit`. - `GET /politician-trades/stats` — aggregate counts/breakdown for the current window. - `GET /politician-trades/by-ticker/:ticker` — congressional trades for one ticker. - `GET /insider` — Form 4 insider trades ($25k+, past 21 days), each row labelled with its side. Params: `direction` (`buy`|`sell`|`other`|`all`, default `buy` — `other` is awards, gifts and tax withholding), `ticker` (filter to one symbol), `limit` (1–200, default 100). Response includes `available: {buy, sell, other}` — pre-filter counts for the whole window, so an empty `buy` result still tells you whether the ticker had sales. - `GET /institutional/buys-sells` — institutional buying/selling by ticker with conviction. Params: `weeks` (1–52, default 2), `minConviction`, `limit` (1–200, default 50). - `GET /institutional/sector-rotation` — net institutional flow direction by sector. - `GET /institutional/divergences` — tickers where institutional positioning diverges from price. - `GET /institutional/divergences/intrashop` — intra-shop divergence alerts (same fund family, opposite sides of one ticker). - `GET /institutional/divergences/:symbol/history` — divergence history for one ticker. - `GET /institutional/:symbol/history` — institutional positioning history for one ticker. - `GET /institutional/etf-options` — ETF institutional options positioning snapshot. > Five routes are deliberately withheld (return 404) because they would otherwise carry raw vendor data (per-contract quotes or intraday price bars) we're not licensed to redistribute: `/ticker/:symbol/options`, `/ticker/:symbol/tactical-grid`, `/ticker/vopr-setups`, `/ticker/:symbol/intraday-chart`, and `/insider/quotes`. This is not a bug — use the derived screener/GEX/edge-grade endpoints instead. ### Market regime - `GET /macro-regime` — Macro regime from Treasury, Federal Reserve, FRED and CFTC series: yield curve and 10Y-2Y spread, 10Y real yield, breakeven, 5Y5Y forward inflation, fed funds, Fed net liquidity, and CFTC E-mini S&P 500 positioning. Units and asOf on every field, plus an interpretation sentence. - `GET /market-internals` — Derived market internals: S&P 500 breadth (percent above 20/50/200-day averages, advancers/decliners, net new 52-week highs, zones), 60-session stock/bond and dollar/equity correlations, cross-asset ratios (VIX/VIX3M term structure, gold, copper-to-gold, oil 20-session changes) and the equity-risk-premium zone with implied ERP. Percent, ratios and correlations only — no index, futures or volatility levels, no fair-value prices. ### Crypto - `GET /crypto/quote?symbols=BTC,ETH` — live USD spot for up to 10 coins: price, 1h/24h/7d/30d change, market cap, 24h volume, circulating/max supply, rank, `lastUpdated`. Returns `notFound` for symbols with no quote. A malformed or over-long list is a `400` with the reason, never a truncated answer. - `GET /crypto/overview?limit=10` — total market cap + 24h change, total 24h volume, BTC/ETH dominance, active-currency count, and the top coins by market cap. `limit` is clamped to 1–25. > Spot only — no options, gamma, flow or apex data exists for crypto on this API. ### Ticker Search - `GET /ticker/search?query=...` — symbol search by name or ticker fragment. - `GET /ticker/:symbol` — price, technicals, and options analytics for any symbol. - `GET /ticker/:symbol/fundamentals` — market cap, P/E, EPS, revenue, float, and more. - `GET /ticker/:symbol/smart-money` — one ticker's smart-money composite: congressional trades (last 90 days), Form 4 insider filings (last 21 days, $25k+, buys AND sells — split on each row's `direction`, never count rows as buys), and ETF institutional flow. ### Long Term & Dividends - `GET /long-term/quality` — ranked Quality Score (0–100): profitability, balance-sheet safety, valuation, payout safety. Params: `minScore`, `minDivYield`, `sector`, `sort` (score|divYield|marketCap|pe), `limit` (default 100, max 500). - `GET /long-term/quality/:symbol` — Quality Score + full fundamental breakdown for one ticker: margins, balance-sheet safety, growth, valuation, next earnings + ex-dividend dates, company profile (`industry`, `founded`, `website`, `sharesOutstanding`), and forward-looking valuation (`forwardPE`, `enterpriseValue`, `revenueTTM`, `eps`, `epsForward`). - `GET /long-term/dividends` — upcoming ex-dividend calendar (ex-div date, pay date, rate, yield). Params: `from` (YYYY-MM-DD), `days` (default 60, max 365), `limit` (default 200, max 500). - `GET /long-term/sectors` — distinct sectors available in the quality dataset. - `GET /long-term/quality-score` — every scored symbol, allow-listed fields only: `symbol`, `sector`, `companyName`, `qualityScore`, `marketCapTier` (1=mega/2=large/3=small-mid — a bucket, not the exact market cap), `updatedAt`. Powers TraderMatrix's own public `/quality-score` pages; no fundamentals (P/E, margins, debt/equity, 52-week range) included. - `GET /long-term/quality-score/:symbol` — one symbol's row from the same allow-list above. ### LLM / agent context - `GET /llm-context/:symbol` — one ticker, one markdown document, built for pasting straight into an LLM's context window. Returns `text/markdown`, not JSON — the only endpoint on this API that does. Sections: dealer gamma regime + flip level, top apex levels, recent unusual-flow rows (score, tier, sentiment, vs-OI and vs-ADV ratios), IV rank, long-term quality score, and the session's directional-flow lean. Derived TraderMatrix signals only — no chains, no quotes, no news. A section with nothing to report prints an explicit "no data" line rather than being omitted. --- ## Code examples ### cURL ```bash curl -H "X-API-Key: td_live_your_key_here" \ "https://api.tradermatrix.pro/api/v1/unusual-activity?minScore=85&timeFrame=today" ``` ### Python ```python import requests API_KEY = "td_live_your_key_here" BASE_URL = "https://api.tradermatrix.pro/api/v1" response = requests.get( f"{BASE_URL}/unusual-activity", headers={"X-API-Key": API_KEY}, params={"minScore": 85, "timeFrame": "today"}, ) data = response.json() for flow in data["data"][:5]: print(f"{flow['ticker']} {flow['sentiment']} ${flow['premium']:,.0f}") ``` ### JavaScript ```javascript const API_KEY = "td_live_your_key_here"; const BASE_URL = "https://api.tradermatrix.pro/api/v1"; const response = await fetch( `${BASE_URL}/unusual-activity?minScore=85&timeFrame=today`, { headers: { "X-API-Key": API_KEY } } ); const { data } = await response.json(); data.slice(0, 5).forEach((flow) => { console.log(`${flow.ticker} ${flow.sentiment} $${flow.premium.toLocaleString()}`); }); ``` --- ## Example: wheel & dividend workflow A common goal is monitoring a wheel / cash-secured-put / DCA income strategy. With the MCP connected, you can drive it all by asking your AI assistant — no code. Under the hood these are the tools it uses: - **Find candidates to sell puts on:** `run_screener` with the `csp-wheel` screener → tickers set up for cash-secured puts. - **Check if premium is worth selling right now:** `get_iv_rank` on a ticker → is implied volatility rich (good to sell) or cheap? - **Pick a strike near a support magnet:** `get_apex_levels` → the OI/gamma "magnet" strikes and the gamma-flip level. - **Get a ranked structure:** `get_strategy_ideas` (or `get_edge_xray` to grade the whole chain). - **Long-term quality of the underlying** (you may get assigned shares): `get_long_term_quality` → is this a name you're happy to own? - **Dividend capture / income timing:** `get_dividend_calendar` → ex-div dates and yields; `get_long_term/dividends` via REST for a full window. - **Avoid event risk:** `get_earnings_flow` and `get_economic_calendar` → don't sell puts into an earnings print or an FOMC day. Example prompt to Claude once connected: > "Using TraderMatrix, run the csp-wheel screener, then for the top 3 names check IV rank and whether they report earnings in the next two weeks. Flag any I should avoid selling puts on right now." --- ## Notes & limits - **No trading.** No order placement and no money movement. Market data is read-only; the only account data the API can change is your own watchlists, via the MCP watchlist tools. - **CORS is open** (any origin) because the API key is the auth. Keep your key private; anyone with it can use your quota. - **User-specific in-app features are not in the public API** (e.g. saving your own screener presets). The core data endpoints all work with just your key. - **No daily cap** beyond the per-minute limit today, but be a good citizen — cache results you re-use. - **`GET /llm-context/:symbol` returns `text/markdown`, not JSON** — every other endpoint on this API returns a JSON body. ## Data usage & redistribution For US equities and equity options, this API serves TraderMatrix's **analytics layer** — scores, levels, rankings, and rollups we compute — and is deliberately **not** a market-data feed. Crypto is the one deliberate exception, called out below. A few things follow from that: - **What you get is derived.** Unusual-activity scores and tiers, GEX and apex levels, conviction, sector and directional flow rollups, screener and quality scores, IV rank, hedge rankings, and the edge X-ray grades. This is our own work product, and your key licenses you to use it. - **What you won't get, by design.** Raw option chains and per-contract bid/ask/greeks or per-strike IV. We license our market data from providers (including Tradier, Alpaca, and Finnhub) whose terms don't permit us to redistribute their raw rows, so we serve the layer we built on top instead. `get_edge_xray` returns rich/cheap and execution grades per contract rather than the quotes behind them — no bid/ask/mid, no per-contract IV or greeks, no open interest or volume; `get_premarket_gappers` returns a `hasNews` boolean rather than headline text. If you need a raw chain or a live quote feed, license one directly from a market-data vendor — that's the correct and cheaper path. - **News is an exception, and this line used to say otherwise.** `get_ticker_news` does return headline text, source and link. An earlier version of this page listed news among the things you would never get; that was inaccurate while the tool was live, and accuracy about what we actually serve matters more than the tidier promise. Headlines belong to their publishers: use them to understand a move, don't republish them as a feed of your own, and attribute the source when you show one. - **The one quote you do get is the underlying's.** `GET /ticker/:symbol` and `GET /ticker/:symbol/fundamentals` include vendor-sourced price and company data for the symbol you asked about, so the analytics on that response have a price to sit against. That is a single-symbol lookup, not a feed: it stays covered by the no-resell rule below, and it is not a substitute for a market-data subscription if what you need is streaming quotes. - **Crypto is the exception, and we say so plainly.** `get_crypto_quote`, `get_crypto_market_overview` and `GET /crypto/*` are **not** a derived layer — they are third-party spot data (price, market cap, volume, supply, dominance) relayed as-is, because there is nothing for us to compute there. Treat them as a convenience lookup beside your equity analytics, not as a licensed crypto feed: the no-resell rule below applies with full force, and if crypto data is what your product is actually built on, license it from a crypto data provider directly. Spot only — there is no options, gamma, flow or apex data for any coin, and there is no plan to add it. - **Market Health is derived, and its limits are deliberate.** The five `market-health` routes and their MCP tools publish ratios, percent changes vs moving averages, correlations, status classifications, percent valuation distances and US-government series (Federal Reserve, NY Fed, Treasury, BEA, CFTC). They do **not** carry raw index, ETF or commodity levels, the third-party-licensed credit-spread series, the economic calendar, or the S&P 500 index level and earnings behind the valuation model. - **Your use is for your own application.** Per the [Terms](https://www.tradermatrix.pro/terms) (§7), don't resell, sublicense, or redistribute the data this API returns as a data product of your own, and don't scrape the site. Building a tool, dashboard, bot, or research workflow on top of it is exactly what it's for. - **Public-source data is exempt — but the exemption follows the SOURCE, not the subject.** Short interest and short volume come straight from FINRA's own published files, so those rows carry no restriction. Congressional STOCK Act disclosures (`/politician-trades`) are also exempt as of 2026-09-19: we parse them ourselves directly from the House Clerk and Senate eFD primary filings, not from a third-party compilation, so those rows carry no redistribution restriction either. Insider Form 4 activity is a different case — the underlying filings are public record and you are free to pull them yourself from SEC EDGAR, but the feed we serve is a third-party compilation of those filings, so those rows stay covered by the no-resell rule above. - **Attribution** ("Powered by TraderMatrix") is appreciated but not required. Questions about a use case that doesn't fit the above — a partnership, white-label, or bulk arrangement — email support and ask. Some of it we can license; some of it isn't ours to license. ## Links - Website page guide (what's on each page, for an agent navigating the site rather than calling the API): https://www.tradermatrix.pro/llms-pages.txt - Developer docs (human-readable): https://www.tradermatrix.pro/developers - Beginner setup walkthrough (no prior config-file experience assumed): https://www.tradermatrix.pro/learn/mcp-setup - Connect your AI overview (example questions, free endpoint, plans): https://www.tradermatrix.pro/arm-your-ai - Agent Skill (for Claude/agentic clients): https://www.tradermatrix.pro/skills/traderdaddy-pro/SKILL.md - OpenAPI 3.0 spec: https://www.tradermatrix.pro/openapi.json - Pricing: https://www.tradermatrix.pro/pricing - Manage API access & keys: https://www.tradermatrix.pro/settings?tab=developer - Support: https://www.tradermatrix.pro/support - Model Context Protocol (what MCP is): https://modelcontextprotocol.io