tradermatrix-pro Signals API

openapi: 3.2.0
info:
  title: TraderMatrix Developer Signals API
  version: 1.0.0
  description: 'Options-flow, gamma exposure (GEX), dark pool, insider, congressional-trade, sector-rotation, screener, and earnings-flow data for US equities.


    This API publishes TraderMatrix''s DERIVED layer only — scores, tiers, levels, and rollups we compute ourselves. It does not redistribute raw vendor rows (per-contract bid/ask/last/greeks, option chains keyed by strike, underlying quote passthrough, or news article text/URLs) — those are licensed from Tradier/Alpaca/Finnhub or scraped from TradingView/ForexFactory/OpenInsider and cannot be redistributed to third parties. Five routes that would otherwise carry raw vendor data (per-contract quotes or intraday price bars) are deliberately withheld (404): `/ticker/{symbol}/options`, `/ticker/{symbol}/tactical-grid`, `/ticker/vopr-setups`, `/ticker/{symbol}/intraday-chart`, and `/insider/quotes`.


    An MCP tool-calling surface is also available at `POST /mcp` (not itself describable by OpenAPI) with 58 tools: 44 read-only market-data tools, 7 for the key owner''s own watchlists (6 of which write), and 7 read-only tools for the key owner''s own positions, trade journal and ConnectTrade-linked broker accounts. The full list is under `info.x-mcp-tools` — see `https://tradermatrix.pro/llms.txt` or the `tradermatrix` Agent Skill at `https://tradermatrix.pro/skills/tradermatrix/SKILL.md`.'
  contact:
    url: https://tradermatrix.pro/developers
  x-mcp-tools:
  - name: get_market_stats
    access: read
    description: SPY/QQQ/IWM put/call ratios, sentiment, and the largest unusual options trade for the current trading date.
  - name: get_macro_regime
    access: read
    description: '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.'
  - name: get_market_internals
    access: read
    description: '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.'
  - name: get_gex_overview
    access: read
    description: Gamma exposure across tracked symbols — flip points and key walls.
  - name: get_gex_ticker
    access: read
    description: Gamma exposure analysis for any single ticker, including a gamma-pocket flag when the name's dealer gamma diverges from the broad-market regime.
  - name: get_apex_levels
    access: read
    description: Composite “magnet” strike ranking (OI walls + net gamma) with the gamma-flip level.
  - name: get_gex_vex_ladder
    access: read
    description: Dealer gamma (USD) and vega (relative, -100..100) side by side for the 13 strikes nearest spot, with a role and a STRONG / MODERATE / OPPOSING alignment tag per strike.
  - name: get_unusual_activity
    access: read
    description: Real-time unusual options activity feed with scoring and sentiment.
  - name: run_screener
    access: read
    description: Run a named screener and return matching tickers with scoring.
  - name: get_sector_flow
    access: read
    description: Options flow aggregated by GICS sector ETF with sentiment breakdown.
  - name: get_put_call_ratios
    access: read
    description: Put/call ratio for a ticker from its nearest weekly expiration. Null when there is no call volume to divide by.
  - name: get_earnings_flow
    access: read
    description: 'Pre-earnings unusual options positioning for tickers reporting soon. Each event carries dateEstimated: true when the report day is a projection the company has not announced (it may move), null when unknown.'
  - name: get_economic_calendar
    access: read
    description: Macroeconomic events — FOMC, CPI, NFP — with consensus estimates.
  - name: get_ticker_snapshot
    access: read
    description: 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.
  - name: get_iv_rank
    access: read
    description: Self-relative IV rank — is a ticker's premium rich or cheap vs its own history? Labelled with its source; percentile accompanies a self-tracked reading.
  - name: get_strategy_ideas
    access: read
    description: Ranked, auto-assembled multi-leg option structures priced off the live chain.
  - name: get_edge_xray
    access: read
    description: Whole-chain rich/cheap grade for one expiration, with optional trade-archetype lens.
  - name: get_hedge_analysis
    access: read
    description: Ranked downside-protection structures for a share position you specify — collars, puts, and spreads priced off the live chain.
  - name: get_institutional_activity
    access: read
    description: Most actively-traded tickers by institutional options-flow volume today, with directional bias.
  - name: get_directional_flow
    access: read
    description: The session's cumulative (from-open) delta-weighted flow lean per underlying — cumΔ, conviction, and a bullish/bearish/balanced bias. Pass a symbol or get the top-15 leaderboard.
  - name: get_dark_pool
    access: read
    description: 'Rolled-up off-exchange (“dark pool”) equity BLOCK flow for a ticker: print count, gross and net notional, accumulation vs distribution split, largest print. Aggregates only, individual prints are not served. 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.'
  - name: get_gap_continuation
    access: read
    description: '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.'
  - name: get_breakout_signals
    access: read
    description: 'Breaking Out scanner: the active daily breakout and continuation signals, newest first. Returns ticker, signal type, direction, the price at detection, stop and target (null when they would sit on the wrong side of entry) and detectedAt. Filter by ticker, direction, since (ISO timestamp) to poll only new signals, and limit.'
  - name: get_breakout_tape_confirmed
    access: read
    description: 'Breakout + Tape Confirmed: Breaking Out names the live options tape is also buying bullish this session. Returns ticker, conviction (0 to 1), firstSeenAt, relative strength vs SPY (percent) and gamma regime. Derived verdicts only; empty outside the session.'
  - name: get_politician_trades
    access: read
    description: Congressional / political stock-disclosure leaderboard — the “Power Players” most-active names.
  - name: get_politician_trades_by_ticker
    access: read
    description: Every congressional / political stock-disclosure trade for a single ticker.
  - name: get_insider_trades
    access: read
    description: Form 4 insider trades of $25k+ filed with the SEC over the past 21 days, market-wide or filtered to one ticker. `direction` defaults to buy; pass sell, other or all.
  - name: get_ticker_news
    access: read
    description: Catalyst news for one ticker — the single most decision-relevant recent headline, a count of hard catalysts in the window, and recent categorized supporting headlines with source and link. Answers "why is $X moving?"; returns null rather than inventing a catalyst when only commentary exists.
  - name: get_crypto_quote
    access: read
    description: 'Live USD spot for named coins (BTC, ETH, SOL, any ticker) — price, 1h/24h/7d/30d change, market cap, 24h volume, supply and rank. Returns notFound for symbols with no quote. Max 10 per call. Spot only: there is no options, gamma or flow data for crypto.'
  - name: get_crypto_market_overview
    access: read
    description: Market-wide crypto read — total market cap and 24h change, total 24h volume, BTC and ETH dominance, active-currency count, and the largest coins by market cap. Dominance describes rotation, not a price target.
  - name: get_short_interest
    access: read
    description: 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.
  - name: get_bounce_signals
    access: read
    description: Bounce Finder screener — recently detected oversold-bounce candidates with scoring.
  - name: get_bounce_score
    access: read
    description: On-demand oversold-bounce composite score for a single ticker.
  - name: get_premarket_gappers
    access: read
    description: 5-pillar momentum gap scan (gap >=10%, price $1-$100, float <=100M, premarket volume >=50k; relative volume ranks the board and news is flagged), runnable on the pre-market or after-hours tape. A common day-trading screen pattern; independent implementation, not affiliated with or endorsed by Warrior Trading or Ross Cameron.
  - name: get_conviction
    access: read
    description: Community Conviction gauge — a 0..100 blended read of how TD Pro traders are leaning on a ticker.
  - name: get_market_health
    access: read
    description: Market Health confluence — 9 macro-regime detectors (risk appetite, credit, breadth, volatility, financial conditions, rotation) rolled into one read.
  - name: get_market_health_history
    access: read
    description: Market Health history — 30 days of composite risk-score snapshots, derived per-detector line series (percent vs moving average, ratios, N-day changes) and status changes since the previous trading day. No raw prices, no calendar rows.
  - name: get_market_valuation
    access: read
    description: S&P 500 valuation verdict from an equity-risk-premium model — implied ERP, distance from the Fair value band and five ERP bands, as percentages only (no index level or earnings inputs).
  - name: get_macro_liquidity
    access: read
    description: US-government macro and liquidity series — Fed net liquidity, real yield, breakevens, fed funds, Treasury yield curve and 10Y-2Y spread, CAPEX and CFTC E-mini S&P 500 positioning. No third-party-licensed credit spreads.
  - name: get_cross_asset_regime
    access: read
    description: Derived cross-asset read — stock-bond and dollar-stock correlations, gold/copper/oil 20-session changes, VIX/VIX3M term structure and MOVE/VIX. No raw index or commodity levels.
  - name: get_market_breadth
    access: read
    description: '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.'
  - name: get_long_term_quality
    access: read
    description: Fundamental quality + dividend screener across the optionable universe for long-term names.
  - name: get_dividend_calendar
    access: read
    description: Upcoming ex-dividend calendar across the optionable universe with yields and pay dates.
  - name: get_ipo_scanner
    access: read
    description: IPO Scanner — the pipeline from pre-IPO chatter to freshly-listed names.
  - name: list_watchlists
    access: read
    description: Your own watchlists — every list with its tickers and notes, plus your list and ticker limits.
  - name: add_to_watchlist
    access: watchlist-write
    description: Add a ticker (with an optional note) to one of your watchlists, or your default list. Re-adding just updates the note.
  - name: remove_from_watchlist
    access: watchlist-write
    description: Remove a ticker from one of your watchlists, or from every list it's on.
  - name: move_watchlist_ticker
    access: watchlist-write
    description: Move a ticker from one of your watchlists to another.
  - name: create_watchlist
    access: watchlist-write
    description: Create a new named watchlist on your account.
  - name: update_watchlist
    access: watchlist-write
    description: Rename one of your watchlists, change its category, or make it your default list.
  - name: delete_watchlist
    access: watchlist-write
    description: Delete one of your watchlists and the tickers on it. Your default list can't be deleted.
  - name: get_my_positions
    access: account-read
    description: 'Your open positions as logged in TraderMatrix: trade journal plus wheel tracker (open CSPs and covered calls), rolled up per holding with lot counts and average entry. Paper trades are flagged; a truncated result says so.'
  - name: get_my_journal_stats
    access: account-read
    description: 'Your trade-journal performance: win rate overall and by idea source, realized P&L, average return on capital. Real-money book, with paper trades summarised separately.'
  - name: get_my_broker_accounts
    access: account-read
    description: 'Brokerage accounts you linked through ConnectTrade: broker, nickname, last 4 of the account number, link health. Needs the ConnectTrade add-on. Linking happens in TraderMatrix, never through the API.'
  - name: get_my_broker_positions
    access: account-read
    description: Live positions from your linked brokerage accounts, each with its own freshness, price-unit basis and broker-reported P&L. Says when an account did not answer.
  - name: get_my_broker_balances
    access: account-read
    description: Live cash, buying power and margin figures from your linked brokerage accounts.
  - name: get_my_broker_transactions
    access: account-read
    description: 'Your broker activity feed: fills, dividends, fees, transfers, newest first, up to 90 days back (some brokers keep less).'
  - name: get_my_portfolio_signals
    access: account-read
    description: 'Every ticker you hold (linked broker accounts plus journal and wheel tracker), each with TraderMatrix''s derived read: gamma regime, nearest Apex level, flow bias, IV rank, quality score and days to earnings. Tickers only; no sizes or P&L.'
servers:
- url: https://api.tradermatrix.pro/api/v1
  description: Production
- url: https://api.traderdaddy.pro/api/v1
  description: Legacy hostname (same server, kept permanently for existing integrations)
security:
- ApiKeyHeader: []
- ApiKeyBearer: []
tags:
- name: Signals
paths:
  /signals:
    get:
      summary: Technical breakout/continuation/triangle signals
      operationId: getSignals
      parameters:
      - name: signalType
        in: query
        schema:
          type: string
          enum:
          - all
          - breakout
          - continuation
          - triangle
          default: all
      - name: ticker
        in: query
        schema:
          type: string
      - name: sectors
        in: query
        schema:
          type: string
        description: Comma-separated sectors
      - name: timeframe
        in: query
        schema:
          type: string
          default: daily
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: OK
      tags:
      - Signals
  /signals/stats:
    get:
      summary: Aggregate signal stats
      operationId: getSignalsStats
      responses:
        '200':
          description: OK
      tags:
      - Signals
  /signals/{id}:
    get:
      summary: One signal by id
      operationId: getSignalById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
      tags:
      - Signals
  /signals/{id}/chart-data:
    get:
      summary: Chart data backing one signal
      operationId: getSignalChartData
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
      tags:
      - Signals
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your td_live_ API key, generated at https://tradermatrix.pro/developers (Pro/Elite plan required).
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: td_live_...
      description: 'Authorization: Bearer td_live_xxxxxxxxxxxxxxxxxxxx — equivalent to X-API-Key.'