---
name: tradermatrix
description: Query TraderMatrix's live options-flow, GEX/gamma, dark pool, insider, congressional-trade, sector-rotation, screener, and earnings-flow data via the Developer API (REST + MCP). Use this when the user asks about unusual options activity, smart money / dark pool flow, GEX or Apex gamma levels, sector rotation, insider Form 4 trades, congressional trades, dividend/quality screeners, or earnings-flow signals for a US equity ticker — or asks about their OWN TraderMatrix positions, trade journal, wheel trades or linked brokerage accounts (ConnectTrade or Robinhood) ("how are my positions looking", "review my week", "anything I hold reporting earnings?") — and a `td_live_` API key is available.
---

# TraderMatrix Developer API

TraderMatrix (tradermatrix.pro) is an options-flow and market-structure
platform. This skill teaches an AI agent how to call its paid Developer API —
REST endpoints under `/api/v1` and an MCP tool surface at `POST /api/v1/mcp` —
to answer questions about unusual options activity, gamma exposure (GEX),
dark pool prints, insider trades, congressional trades, sector rotation, and
related derived signals for US equities.

This is a **customer-facing developer product**, separate from the TraderMatrix web
app. It requires the user's own API key. If no key is available, tell the
user to generate one at `https://www.tradermatrix.pro/settings?tab=developer` and
stop — do not guess a key or fabricate data.

Access tiers: free accounts get a 25-call/day MCP preview (lists cut to the first
3 items, a `preview` field on every result); Premium members get MCP access (200
tool calls/day); both are limited to 12 tool calls per minute per account. The
Developer API add-on unlocks REST + higher limits. If a tool returns "Daily limit
reached" or "Premium feature", relay the upgrade link to the user rather than
retrying; on "Slow down" or "TraderMatrix is busy", wait a minute before retrying.

## Authentication

Every request needs the key as either header:

```
X-API-Key: td_live_xxxxxxxxxxxxxxxxxxxx
```

or

```
Authorization: Bearer td_live_xxxxxxxxxxxxxxxxxxxx
```

Rate limit: 30 requests/minute per key. A 429 response means back off; do not
retry in a tight loop.

Base URL: `https://api.tradermatrix.pro/api/v1`

## Two ways to call this API

### Option A — MCP (preferred when your client supports MCP tool-calling)

Point an MCP-capable client at:

```json
{
  "mcpServers": {
    "tradermatrix": {
      "type": "http",
      "url": "https://api.tradermatrix.pro/api/v1/mcp",
      "headers": { "X-API-Key": "td_live_xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

`tools/list` returns 63 tools: 45 read-only market-data tools, 7 that
work on the key owner's own watchlists (list, add, remove, move, create,
update, delete), and 8 read-only `get_my_*` tools for the key owner's own
positions, trade journal and linked broker accounts (ConnectTrade or Robinhood), and 3 read-only skills tools (`list_skills`, `get_skill`, `get_my_skills`) for the skills library and the key owner's own saved skills. The market-data set covers unusual activity, GEX/apex levels,
sector flow, insider trades, congressional trades, screeners, earnings flow,
dark pool, directional flow, IV rank, expected move, edge X-ray, Market Health, and more). Tool names and
descriptions are self-documenting — call `tools/list` first rather than
memorizing the set here, since it changes as tools ship.

⚠️ **`type: "http"` is required** in a `.mcp.json` / `claude_desktop_config.json`
entry. Claude Desktop/Code treat a bare `{"url": ...}` object as a stdio
server and will fail to connect. Cursor tolerates a bare `url`. The Claude
Code CLI can also add it directly: `claude mcp add --transport http
tradermatrix https://api.tradermatrix.pro/api/v1/mcp --header "X-API-Key:
td_live_xxx"`.

**Gemini CLI** (`~/.gemini/settings.json`) uses `httpUrl`, not `url` — there
`url` means SSE, which this endpoint does not serve:

```json
{
  "mcpServers": {
    "tradermatrix": {
      "httpUrl": "https://api.tradermatrix.pro/api/v1/mcp",
      "headers": { "X-API-Key": "td_live_xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

**Codex** (`~/.codex/config.toml`) reads the key from an environment
variable; `bearer_token_env_var` is the variable's name, not the key:

```toml
[mcp_servers.tradermatrix]
url = "https://api.tradermatrix.pro/api/v1/mcp"
bearer_token_env_var = "TRADERMATRIX_API_KEY"
```

### Option B — Plain REST (when you just need one HTTP call)

Every REST route below returns JSON (except `/llm-context/:symbol`, which
returns plain markdown). Full machine-readable schema:
`GET https://tradermatrix.pro/openapi.json`.

## What this API will and will not return (read before building anything)

TraderMatrix licenses most of its underlying market data (Tradier, Alpaca,
Finnhub) or scrapes it (TradingView, ForexFactory, OpenInsider) — it does not
own it, and none of those sources permit redistributing raw rows to a third
party. So the API publishes a **derived** layer only:

- 🟢 Returned: unusual-activity scores/tiers/sentiment, GEX/Apex gamma levels
  and flip points, sector-flow rollups, screener scores, IV rank, edge-grade
  metrics, dark-pool net-notional rollups, SEC/FINRA/House-Clerk/Senate-eFD
  sourced insider and congressional trade rows.
- 🔴 Never returned: per-contract bid/ask/last/greeks, raw option chains keyed
  by strike, underlying quote passthrough, or news article text/URLs. Five
  routes that would otherwise carry raw vendor data (per-contract quotes or
  intraday price bars) — `/ticker/:symbol/options`,
  `/ticker/:symbol/tactical-grid`, `/ticker/vopr-setups`,
  `/ticker/:symbol/intraday-chart`, and `/insider/quotes` — are deliberately
  withheld (404) on this API. Use
  `get_edge_xray` (MCP) or the derived screener/GEX endpoints instead of
  trying to reconstruct a chain.

If a task needs a live bid/ask or a full option chain, this API cannot do
it — say so rather than approximating from a derived score.

The one exception is the key owner's **own** records (next section): their
broker positions, balances and fills come back as their broker reported them,
because they are the user's data, not ours.

## The key owner's own portfolio (MCP only)

Seven read-only `get_my_*` MCP tools read the account that owns the API key.
There is no way to name another account, and nothing here can link or unlink a
broker, place an order or edit a record — those happen in TraderMatrix itself.
They are MCP-only (no REST route) and answer "Premium feature" on a free preview key.

| Tool | Use it for |
|---|---|
| `get_my_portfolio_signals` | **Start here for "how are my positions looking?"** Every ticker the user holds (linked broker + journal + wheel tracker), largest position first, each with our derived read: gamma regime, nearest Apex level, flow bias, IV rank, quality score, days to earnings. Tickers only — no sizes or P&L. |
| `get_my_holdings_levels` | **"Which of my positions are near a wall or below the flip?"** Every ticker in their real-money journal against its dealer levels: support or resistance zone, gamma regime, walls, flip, magnet, and a one-line interpretation. Derived only, no prices. Context on dealer positioning, never a forecast or a buy/sell call. |
| `get_my_broker_positions` | What they actually hold at their broker: quantity, average cost, broker-reported P&L, per-row freshness. |
| `get_my_broker_balances` | Cash, buying power and margin per linked account. |
| `get_my_broker_transactions` | Fills, dividends, fees and transfers, newest first, up to 90 days (some brokers keep less). |
| `get_my_broker_accounts` | Which brokers are linked (ConnectTrade or Robinhood) and whether each link is healthy. |
| `get_my_positions` | What they LOGGED in TraderMatrix: open journal lots and wheel-tracker CSPs / covered calls, rolled up per holding. |
| `get_my_journal_stats` | Win rate, realized P&L and return on capital, by idea source; real-money book with paper trades separate. |

**Workflows**

- *"How's my portfolio?"* → `get_my_portfolio_signals`, then `get_my_broker_positions`
  (or `get_my_positions` when no broker is linked) for the size and P&L behind the
  names that stand out.
- *"Is anything I hold beyond a wall?"* → `get_my_holdings_levels`; read `zone` and
  `interpretation`, and `get_expected_move` for the size of move on that ticker.
- *"Anything I hold reporting soon?"* → `get_my_portfolio_signals`; read
  `daysToEarnings` and pair it with `ivRank` on those rows.
- *"Should I keep covering / is my CSP in trouble?"* → `get_my_positions` for the
  strike and expiry, then `get_gex_ticker` / `get_apex_levels` on that ticker for
  the levels around it.
- *"Review my week"* → `get_my_broker_transactions` with `days: 7`, then
  `get_my_journal_stats` for how the logged trades are scoring.

**Rules that keep the answer honest** (every payload repeats these in a field)

- **Broker first.** The broker is what they hold; the journal is what they
  logged. When a broker is linked, quote size and basis from
  `get_my_broker_positions`, and say so when the two disagree.
- **`complete: false`** means a linked account did not answer or the list was
  cut. Name what is missing; never describe the rest as the whole portfolio.
- **Count from `accounts[].position_count`**, never from the length of an array.
- **A null P&L means "not reported", never zero.** Some brokers (Schwab) report none.
- **Read each price's `*_basis`** (`per_share` / `per_contract` / `unknown`)
  before scaling it. A negative quantity is a short.
- **`is_paper` rows are simulations**, not exposure.
- **Signals describe the ticker, not the position.** A gamma regime or flow bias
  never tells the user their trade is right or wrong; don't turn one into a
  buy/sell instruction.
- `connected: false` means nothing is linked HERE — not that they hold nothing.
  Linking happens at `https://www.tradermatrix.pro/journal/positions`; each
  provider (ConnectTrade, Robinhood) needs its own entitlement.
- Every broker row carries its own `provider` (`"connecttrade"` or `"robinhood"`);
  an optional `provider` argument narrows a read to one side.

## Common REST endpoints

All query params below are optional unless noted; defaults shown. Full param
list, types, and every route: `GET /openapi.json`.

| Endpoint | What it returns |
|---|---|
| `GET /unusual-activity?ticker=&timeFrame=today&minScore=95` | Scored unusual options flow, filterable by premium/DTE/sentiment/tier |
| `GET /unusual-activity/repeats?hours=24` | Tickers with repeated opening flow in a window |
| `GET /gex/:symbol` | Gamma exposure by strike for one ticker |
| `GET /gex/:symbol/apex` | Apex gamma-magnet levels (premium) |
| `GET /gex/market/overview` | Market-wide gamma bias snapshot |
| `GET /options/expected-move/:symbol` | Options-implied expected-move ladder: lognormal 68%/95% bands + historical hold rates (derived, rounded) |
| `GET /sectors/flow?window=1d` | Sector-level options-flow rollup |
| `GET /sectors/dashboard?window=today` | Macro hero + sector grid + technicals (premium) |
| `GET /sectors/rotation?trail=10` | RRG-style sector rotation map vs SPY |
| `GET /flow/summary?minPremium=20000&days=3` | Cross-market flow summary, filterable |
| `GET /flow/ticker/:ticker` | Flow summary for one ticker |
| `GET /screeners` | List available screeners |
| `POST /screeners/:id/run` | Run a screener (params in JSON body, not query string) |
| `GET /institutional/buys-sells` | Institutional (13F) buy/sell aggregation |
| `GET /institutional/sector-rotation` | Institutional sector rotation |
| `GET /politician-trades?days=30` | Congressional trades, parsed from House Clerk + Senate eFD filings (our compilation — no-resell terms apply) |
| `GET /insider?direction=buy&limit=100` | Form 4 insider trades (default: buys only; pass `direction=all` for both) |
| `GET /earnings?week=current` | Earnings calendar |
| `GET /earnings-flow/flow?days=7` | Pre-earnings options flow buildup |
| `GET /long-term/quality?minScore=&sector=` | Long-term quality/dividend screener |
| `GET /economic-calendar?week=current` | Macro calendar |
| `GET /economic-calendar/predictions` | Kalshi market-implied odds for high-impact events |
| `GET /put-call-ratios` | SPY/QQQ/IWM put-call ratios |
| `GET /market-pulse` | AI-generated market sentiment narrative |
| `GET /market-pulse/thermal` | Per-ticker technicals (RSI/Stoch/MACD/ADX/CCI) for SPY/QQQ/IWM/GLD/IBIT + VIX — not breadth |
| `GET /market-stats` | Aggregate market stats |
| `GET /market-health` | Market Health composite risk score + every detector's status (derived detail only) |
| `GET /market-health/history` | 30-day risk-score snapshots, derived per-detector lines, status changes |
| `GET /market-health/valuation` | S&P 500 equity-risk-premium valuation verdict (percentages only) |
| `GET /market-health/macro` | US-government macro/liquidity series: net liquidity, yields, curve, CFTC positioning |
| `GET /market-health/cross-asset` | Derived cross-asset correlations, ratio changes, VIX/VIX3M term structure |
| `GET /market-health/breadth` | S&P 500 breadth aggregates (percentages and counts only) |
| `GET /macro-regime` | Treasury yield curve, real yield, breakeven, 5y5y, Fed net liquidity and CFTC positioning (public-domain series only) |
| `GET /market-internals` | Breadth, cross-asset ratios and the equity risk premium zone (derived, scale-free values only) |
| `GET /scans/breakout-tape-confirmed` | Breaking Out names the live options tape is also buying bullish (derived verdicts only) |
| `GET /bounce-finder?direction=all` | Oversold/overbought bounce candidates |
| `GET /ticker/search?query=` | Ticker/company search |
| `GET /ticker/:symbol` | Ticker overview |
| `GET /ticker/:symbol/smart-money` | Smart-money flow summary for one ticker |
| `GET /llm-context/:symbol` | One ticker, everything, as plain markdown — built for pasting into an LLM context window |

## Worked example

```bash
curl -s "https://api.tradermatrix.pro/api/v1/unusual-activity?ticker=NVDA&timeFrame=today" \
  -H "X-API-Key: td_live_xxxxxxxxxxxxxxxxxxxx"
```

## Gotchas

- `POST /screeners/:id/run` takes params in a **JSON request body**, not a
  query string — the only endpoint on this API shaped that way.
- Screener runs (`/screeners/:id/run`) are the exception to the 400 rule
  below: params are clamped to each screener's bounds and unknown keys are
  dropped. A **503** means the screener's data source failed (retry shortly;
  an empty match is a 200 with empty `results`), and a **429** means too many
  runs: wait `retryAfter` seconds.
- Tickers are matched case-sensitively as uppercase (`NVDA`, not `nvda`).
- `days`/`hours`/`limit` params are validated server-side (e.g.
  `unusual-activity/repeats?hours=` caps at 72); an out-of-range value
  returns HTTP 400, it is not silently clamped.
- Some routes are premium-gated even for API-key callers if the endpoint
  serves per-contract-adjacent data (e.g. `/sectors/rotation`,
  `/gex/:symbol/apex`). Every `td_live_` key is treated as premium-tier, so
  these all work — you don't need to do anything differently.
- `/ticker/:symbol/options`, `/ticker/:symbol/tactical-grid`, and
  `/insider/quotes` return 404 on purpose (raw per-contract quote data,
  licensing-restricted). This is not a bug.

## More

- Full endpoint catalog + beginner MCP setup walkthrough:
  `https://tradermatrix.pro/llms.txt`
- Interactive docs, code snippets, key management:
  `https://tradermatrix.pro/developers`
- Machine-readable OpenAPI 3 spec: `https://tradermatrix.pro/openapi.json`