QuantLogix Signal API

Real-time multi-factor stock signals for any US equity or ETF. One API call — composite intelligence from technical analysis, momentum, fundamentals, microstructure, and options flow.

Authentication

All API requests require an API key. Pass it via:

# Authorization header (recommended)
curl -H "Authorization: Bearer ql_your_key_here" https://quantlogix.ai/api/v1/signal?ticker=NVDA

# X-API-Key header
curl -H "X-API-Key: ql_your_key_here" https://quantlogix.ai/api/v1/signal?ticker=NVDA

# Note: passing the key as a ?apikey= query parameter is no longer supported —
# query strings are written to access logs, which would leak your key.

API Access

API access starts free — every account can generate a key. Generate keys from your profile page; the same ql_ keys also work with the MCP server for AI agents.

Endpoints

GET /api/v1/signal

Real-time composite signal for any US stock or ETF.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)

Response:

{
  "ticker": "NVDA",
  "signal": "Strong Buy",
  "composite_score": 72,
  "confidence": 55,
  "scores": {
    "technical": { "score": 78, "weight": 0.55, "details": { "rsi": 58.3, "sma_20": 132.45, "sma_50": 128.90, "sma_200": 115.20, "macd_histogram": 1.234 } },
    "momentum": { "score": 65, "weight": 0.45, "details": { "change_pct": 2.15, "volume_ratio": 1.42 } }
  },
  "price": { "current": 135.50, "prev_close": 132.75, "change": 2.75, "change_pct": 2.07, "vwap": 134.20, "volume": 45200000, "after_hours": 136.10 },
  "indicators": { "rsi": 58.3, "sma_20": 132.45, "sma_50": 128.90, "sma_200": 115.20, "macd_histogram": 1.234 },
  "microstructure": { "score": 68, "health": { "label": "Healthy" }, "bias": { "direction": "Bullish", "strength": 3 } },
  "timestamp": "2026-03-31T12:00:00.000Z"
}

GET /api/v1/microstructure

Market microstructure analysis — VPIN, Amihud illiquidity, Kyle's lambda, order flow, smart money, institutional flow. Institutional tier only.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)

Response includes: VPIN, Amihud Illiquidity, Kyle's Lambda, Roll Spread, Bid-Ask Spread, Order Flow Imbalance, RVOL, HV 30-Day, Intraday Volatility, Point of Control, Smart Money Index, Price Efficiency, Volatility Regime, Institutional Flow (buy/sell %), Volume Profile, Hourly Volume Distribution, Cumulative Volume Delta.

GET /api/v1/news

Multi-source aggregated news — Finnhub, Yahoo Finance, CNBC. Deduplicated and sorted by date. Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)
limit	integer	Max articles to return (default 10, max 50)

GET /api/v1/startup-news

StartupPulse — startup-ecosystem news from TechCrunch (startups + venture), VentureBeat, Sifted, Hacker News, Product Hunt and the startup-relevant slice of the QL news engine. Deduplicated, sentiment-scored with a startup lexicon, and funding rounds extracted (stage, amount, lead investor). Refreshed hourly. Available on the Free tier.

Parameter	Type	Description
q	string	Company search — matches company tags, titles and summaries
funding	boolean	true → only stories with an extracted funding round
topic	string	ai, fintech, climate, health, space, defense, robotics, saas
source	string	Restrict to one source key (e.g. techcrunch_startups, sifted)
since	string	ISO date floor on published_at
limit	integer	Max articles (default 20, max 50)

GET /api/v1/promise-ledger

Management Promise Ledger — every forward commitment from earnings-call transcripts stamped kept / missed / walked-back / pending, with the exact triggering sentence as the receipt, plus a 0–100 credibility index and archetype. Same engine as /promise-ledger. Pass demo=1 for the fictional Meridian Compute ledger (no transcript quota). Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock ticker (required unless demo=1)
quarters	integer	Published quarters to score (2–8, default 6)
demo	integer	1 → fictional Meridian Compute (MRDC) ledger

GET /api/v1/readthrough-basket

Private→public read-through basket — generated equal-weight sleeve from the crossmarket graph (named rivals first, then suppliers/investors, then customers/comps), with a live 5-factor roll-up. Same engine as /readthrough-basket. Pass demo=1 for the fictional Helios Robotics sleeve. Pro+ (private-companies family).

Parameter	Type	Description
slug	string	Private-company slug (required unless demo=1)
demo	integer	1 → fictional Helios Robotics sleeve
max	integer	Holdings cap (5–10, default 10)

GET /api/v1/seasonality

Calendar-month seasonality profile from up to 15 years of adjusted daily history — the API behind the QL Seasonality Map. The in-progress month is excluded from the stats and reported separately. Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)

Response:

{
  "ticker": "NVDA",
  "month_count": 179,
  "years_covered": 14.9,
  "from": "2011-07", "to": "2026-07",
  "months": [
    { "month": 1, "label": "Jan", "n": 15, "avg": 0.013, "median": 0.0159, "win_rate": 0.6,
      "best": { "year": 2019, "ret": 0.0801 }, "worst": { "year": 2022, "ret": -0.0527 } }
  ],
  "strongest": { "month": 5, "label": "May", "avg": 0.1224 },
  "weakest": { "month": 12, "label": "Dec", "avg": -0.015 },
  "current": { "month": 7, "label": "Jul", "avg": 0.058, "win_rate": 0.6429, "n": 14, "partial_ret": 0.011 },
  "api_version": "v1"
}

GET /api/v1/gap-stats

Overnight-gap profile from up to 10 years of adjusted daily history — the API behind QL Gap Stats. Fill rate and follow-through by direction and gap size, plus the largest gaps on record and the most recent gap's outcome. A gap counts at ≥0.5% and is filled when the session trades back to the prior close. Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)

Response:

{
  "ticker": "TSLA",
  "sessions": 2514, "from": "2016-07-12", "to": "2026-07-10",
  "gap_count": 1493, "gap_frequency": 0.5939,
  "up": { "n": 782, "fill_rate": 0.62, "follow_rate": 0.48, "avg_gap": 0.021, "avg_open_close": -0.001 },
  "dn": { "n": 711, "fill_rate": 0.58, "follow_rate": 0.51, "avg_gap": -0.02, "avg_open_close": -0.003 },
  "buckets": [
    { "dir": "up", "size": "small", "label": "0.5–1%", "n": 231, "fill_rate": 0.81, "follow_rate": 0.42, "avg_gap": 0.0074, "avg_open_close": 0.0011 }
  ],
  "recent": { "window": "last 252 sessions", "gap_count": 148, "up": { }, "dn": { } },
  "largest_up": [ { "date": "2020-02-04", "gap": 0.1213, "dir": "up", "filled": false, "open_close": 0.017 } ],
  "largest_dn": [ ],
  "last_gap": { "date": "2026-07-10", "gap": -0.011, "dir": "dn", "filled": true, "open_close": 0.004 },
  "api_version": "v1"
}

GET /api/v1/street-grades

Wall Street report card from up to 6 years of analyst rating actions — the API behind QL Street Grades. Post-upgrade and post-downgrade forward returns vs the stock's own baseline drift, the 12-month price-target hit rate, and a per-firm "beat the tape" leaderboard. Forward returns start at the close of the action day; actions without a complete horizon window are excluded. Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)

Response:

{
  "ticker": "NVDA",
  "from": "2020-07-14", "to": "2026-07-10",
  "actions_total": 1214, "upgrade_count": 38, "downgrade_count": 21, "firms_covered": 62,
  "read": "Upgrades on this name have beaten the tape — worth a look when one lands.",
  "edge_3m": { "upgrades": 0.043, "downgrades": -0.021 },
  "scoreboard": {
    "m1": { "upgrades": { "n": 34, "median": 0.062, "win_rate": 0.71 }, "downgrades": { "n": 19, "median": -0.011, "win_rate": 0.47 } },
    "m3": { }, "m6": { }
  },
  "baseline": { "m1": { "n": 1483, "median": 0.031, "win_rate": 0.63 }, "m3": { }, "m6": { } },
  "targets": { "scored": 512, "hit_rate_12m": 0.64, "median_implied": 0.18, "median_realized_12m": 0.42 },
  "firms": [ { "firm": "Morgan Stanley", "calls": 6, "beat_tape": 5, "beat_rate": 0.8333, "last_action": "2026-05-29" } ],
  "recent": [ { "date": "2026-06-05", "firm": "China Renaissance", "action": "initiates_coverage_on", "rating": "buy", "pt": 319, "ret_since": 0.021 } ],
  "api_version": "v1"
}

GET /api/v1/dca

Dollar-cost-averaging backtest on real adjusted history — the API behind QL DCA Lab. Buys at the first session's close of each month with fractional shares; returns money-weighted XIRR, max drawdown, perfect-vs-worst-timing counterfactuals, lump-sum comparison, and the same plan run on SPY. Available on the Free tier.

Parameter	Type	Description
ticker	string	Stock or ETF ticker symbol (required)
monthly	integer	Dollar amount invested each month, 10–1000000 (default 500)
years	integer	Backtest lookback in years, 1–15 (default 10)

Response:

{
  "ticker": "AAPL",
  "monthly_amount": 500, "purchases": 120,
  "from": "2016-08-01", "to": "2026-07-10", "years": 9.9,
  "invested": 60000, "final_value": 154210.55,
  "profit": 94210.55, "multiple": 2.5702, "xirr": 0.1731,
  "max_drawdown": -0.31,
  "best_purchase": { "date": "2016-08-01", "price": 24.15 },
  "worst_purchase": { "date": "2024-12-02", "price": 239.59 },
  "lucky": { "invested": 60000, "final_value": 162874.2, "multiple": 2.7146, "xirr": 0.1852 },
  "unlucky": { "invested": 60000, "final_value": 146530.9, "multiple": 2.4422, "xirr": 0.1614 },
  "lump_sum": { "final_value": 428101.3, "multiple": 7.135, "xirr": 0.2199 },
  "series": [ { "t": 1470024000000, "invested": 500, "value": 500 } ],
  "benchmark": { "ticker": "SPY", "invested": 60000, "final_value": 121002.4, "multiple": 2.0167, "xirr": 0.1341, "purchases": 120 },
  "api_version": "v1"
}

GET /api/v1/earnings-setup

Pre-earnings setup intelligence — estimated next earnings date (labeled est.), options-implied move (ATM straddle), analyst revision momentum + price-target consensus, the engine's 5-factor signal read, YoY fundamentals trend, and recent reported actuals. Requires Pro tier or higher.

Parameter	Type	Description
ticker	string	US ticker symbol (required)

GET /api/v1/earnings-calendar

One company's earnings calendar — the last eight quarterly reports (EPS basic/diluted, revenue, net income, filing date), YoY revenue and EPS growth, and the next report date. The next date is estimated from the company's filing cadence, not a confirmed date, and the response says so (next_earnings_is_estimate: true). Same data as the MCP get_earnings_calendar tool. Requires Pro tier or higher.

Parameter	Type	Description
ticker	string	US ticker symbol (required)

Response includes: next_earnings_estimate · days_until_earnings · earnings_history[] · revenue_growth_yoy · eps_growth_yoy · total_reports.

GET /api/v1/corporate-events

One company's corporate-event timeline in a single call: earnings (with EPS vs estimate), dividends (ex-date, pay date, amount, yield), stock splits, analyst rating changes and price targets, insider (Form 4) transactions, SEC filings, conferences, and M&A / corporate news. Returned both as a unified upcoming / recent timeline and grouped by type. Same data as the MCP get_corporate_events tool. Requires Pro tier or higher.

Parameter	Type	Description
ticker	string	US ticker symbol (required)

Response includes: company · summary (counts, earnings/dividend/analyst roll-ups) · upcoming[] · recent[] · events {earnings, dividends, splits, analyst, insider, filings, conferences, corporate} · related.

GET /api/v1/catalysts

The market-wide forward calendar: every dated, scheduled event in the window — who reports earnings when, IPOs, dividend ex-dates, stock splits, macro prints, index/options expiry, and disclosed Congress trades. Omit ticker for the whole market, or pass one to scope to a single name. Same tape as the MCP get_catalysts tool and the Catalyst Calendar page. Available on every tier — the window and event types are clamped (never refused): Free 7 days of earnings/macro/opex, Starter 21 days of every type, Pro and above the full 60 days. The response's clamped field tells you when your request was narrowed.

Parameter	Type	Description
days	integer	Forward window, 1–60 (default 21), clamped to your tier
types	string	CSV of earnings, ipo, dividend, split, macro, opex, congress. Default: every type your tier allows
ticker	string	Scope to one name. Optional — omit for the market-wide calendar

Response includes: today · window_days · count · events[] · tier · limits · clamped {days, types}.

GET /api/v1/engine/model-card

The engine "model card" — one machine-readable snapshot of the signal engine's measured performance and its four-stage statistical validation, computed on the immutable, auto-resolved track record (the same live numbers shown at quantlogix.ai/proof). Built for quant due-diligence, monitoring pipelines, and AI clients. Requires Pro tier or higher.

Parameter	Type	Description
window	string	Measurement window: 30d | 90d | 365d | all (default 90d)

Response includes: record (n resolved, win-rate + Wilson 95% CI, avg direction-adjusted return, return t-test, per-trade Sharpe) · validation — four graded stages: significance (is the measured edge statistically real), calibration (ECE + Brier — do stated probabilities match realized outcomes), discrimination (ROC-AUC / Gini / rank-IC — does a higher score rank winners higher), robustness (probabilistic Sharpe, minimum track-record length, out-of-sample hold, time consistency, max drawdown, edge trend) · factor_health (per-factor walk-forward IC verdicts: STABLE / DECAYING / BROKEN / INVERTED). Sections degrade to null independently if upstream data is briefly unavailable. All figures are measured past performance — not a guarantee of future results.

GET /api/v1/private-companies/list

Curated database of ~30 hot private/late-stage companies (Anthropic, OpenAI, Stripe, Databricks, SpaceX, etc.) with valuations, funding rounds, investors, and IPO status. Requires Pro tier or higher.

Parameter	Type	Description
sector	string	Filter by sector (e.g. AI, Fintech, Defense). Optional.
q	string	Free-text search across name, slug, tagline, tags. Optional.
limit	integer	Max results (default 50, max 200).

GET /api/v1/private-companies/{slug}

Full profile for one private company, merged with the live enrichment overlay — the 6-hourly deep-enrich pipeline (web + SEC EDGAR) keeps valuation marks and C-suite leadership current between curated refreshes. Requires Pro tier or higher.

Response includes: name, tagline, sector, founded, HQ, employees, CEO, founders, current_valuation_usd, valuation_as_of, valuation_source (URL provenance when the live pipeline sourced the mark), leadership (live-tracked C-suite changes: per-title name / appointed-or-departed / as-of / source), last_round, total_raised_usd, investors, products, competitors, ipo_status, rumored_ipo_year, estimated_revenue_usd, growth_descriptor, news_topics.

GET /api/v1/private-companies/ipo-readiness

5-axis private→public IPO-readiness composite (signal / scale / maturity / growth / liquidity) with band + timing estimate. Pass slug for one company, or omit it for the ranked readiness universe. Requires Pro tier or higher.

Parameter	Type	Description
slug	string	Company slug for a single-company score. Optional — omit for the ranked universe.
sector	string	Sector filter for the ranked universe. Optional.
limit	integer	Max ranked results (default 20, max 40).

GET /api/v1/private-companies/liquidity

Secondary-market liquidity read: marks, instruments, and the restriction/timing model for one company (slug), or the directory of companies with active secondary marks (no slug). Marks are model-derived unless a live secondary feed is configured — the payload discloses which. Requires Pro tier or higher.

GET /api/v1/private-companies/marks

QL Private Marks — one model-marked valuation per tracked private company: the last disclosed round blended with the daily secondary-market print and a public-comps implied valuation, freshness-weighted, with a stated confidence grade, an evidence basis, and full per-component provenance on every row. Methodology ships in the payload. Model estimates for research, not quotes or advice. Requires the Institutional tier.

Parameter	Type	Description
confidence	string	Filter by confidence grade: high, medium, low.
basis	string	Filter by evidence basis: blended, secondary_led, comps_led, round_anchored.
limit	integer	Max rows (default 100, max 3000; all for the full board).

GET /api/v1/private-companies/secondary-tape

QL Secondary Tape — the observed layer of private-market pricing: real, citable secondary-market events (tender offers, reported block sales, marketplace-published indications), one row per company with the full event history. Every event is dated, classified by how it is known (disclosed / reported / indicative) and carries the source URL that backs it; headline numbers come from the best print and are compared to the QL anchor mark. This surface never models — no event, no row. Requires the Institutional tier.

Parameter	Type	Description
slug	string	One company's full tape (404 when it has no observed events).
sort	string	Board ordering: fresh (default), value, premium, prints.
kind	string	Only events of one kind: tender, block, indication, authorized_secondary.
confidence	string	Only events known one way: disclosed, reported, indicative.
limit	integer	Max rows (default 200, max 1000; all for the full board).

GET /api/v1/private-companies/stake-map

QL Stake Map — the disclosed public↔private ownership bridge: which listed companies hold real, sourced stakes in the private roster (Microsoft in OpenAI, Amazon and Alphabet in Anthropic, Tencent / Disney / Sony in Epic Games, …). Each stake is dated, classified by how it is known (disclosed / reported), sized on a stated basis (stated value, else stated % × the QL anchor; capital invested is never used as current value), and carries its source URL — plus the exposure $10,000 of the holder buys of the private name (null when either side is undisclosed; unknown is never zero). Nothing is inferred from partnerships. Single-company ?slug= answers on every key; the board and ?view=holders books require Pro.

Parameter	Type	Description
slug	string	One company's full listed-owner list (any key; 404 when no qualifying stake is curated).
view	string	holders — the reverse index: each listed holder's private book (Pro).
sort	string	Board ordering: value (default, sized backing), holders, fresh.
limit	integer	Max rows (default 200, max 1000; all for the full board).

GET /api/v1/investors/fit

Rank the investors most likely to invest right now in a company profile — deployment pace, dry-powder model, check-size / sector / stage / geo fit over the curated investor database. Provide at least one of sector, stage, geo, raising_usd. Requires Pro tier or higher.

Parameter	Type	Description
sector	string	Company sector (e.g. ai, fintech).
stage	string	Round stage (e.g. seed, series b, growth).
geo	string	Company geography (e.g. us, europe).
raising_usd	number	Target raise in USD.
limit	integer	Max ranked investors (default 12, max 25).

GET /api/v1/private-companies/news

Recent news mentioning a private company, aggregated across 14 sources (Market Wire, Finnhub, Yahoo, CNBC, Seeking Alpha, AV, NewsAPI, MarketWatch, WSJ, Bloomberg, NYT, Reuters, AP) plus Google News. Pass slug for relevance scoring against the company's curated boost terms. Requires Pro tier or higher.

Parameter	Type	Description
q	string	Search query — typically the company name (required, max 80 chars).
slug	string	Optional — when set, articles are scored using the company's curated boost terms (products, CEO, news topics) for higher relevance.

GET /api/v1/investors/list

Curated investor database of ~280 VC / Growth-PE / Corporate-VC / Sovereign-wealth firms (Andreessen Horowitz, Sequoia, Founders Fund, Thrive, Tiger Global, etc.) with AUM, active fund, stage + sector focus, notable partners, notable portfolio companies, and recent investments. Requires Pro tier or higher.

Parameter	Type	Description
firm_type	string	Filter by firm type: VC | Growth/PE | Strategic/CVC | Sovereign. Optional.
q	string	Free-text search across name, tagline, tags, partners. Optional.
sort	string	aum (default) | name | founded.
limit	integer	Max results (default 50, max 200).

GET /api/v1/investors/{slug}

Full profile for one investor / fund. Falls back to the Form ADV corpus for firms outside the curated set. Requires Pro tier or higher.

Response includes: name, short_name, tagline, firm_type, subtype, founded, hq, country, geo_focus, website, aum_usd, aum_as_of, active_fund, stage_focus, sector_focus, notable_partners, notable_portfolio, exits_highlight, recent_investments, tags, news_topics.

Strategy Backtest NEW

Point-in-time historical replay of one classic timing strategy on ONE instrument vs buy-and-hold — the same engine the Alpha Engine Week-10 Strategy Backtest Lab uses, exposed as a JSON endpoint. Returns strategy and buy-and-hold metrics (total return, CAGR, annualized Sharpe, max drawdown, exposure, trade count), the per-metric edge delta, a walk-forward (train 70% / test 30%) Sharpe pair with an OVERFIT / MILD_DECAY / ROBUST / NO_EDGE verdict, and a down-sampled equity curve for charting. Requires Starter tier or higher. No AI tokens are spent — this is pure math over daily closes.

GET /api/v1/backtest/library

Discovery endpoint — returns the catalog of runnable strategy IDs (currently buy_hold, trend, golden_cross, rsi_meanrev, macd), their descriptions, and the full metrics contract every backtest returns. Call this once, cache the result, then loop over strategies[]. Available on every tier (including Free) and never consumes quota.

GET /api/v1/backtest

Run one backtest.

curl -X POST https://quantlogix.ai/api/v1/backtest \
  -H "Authorization: Bearer ql_your_key" -H "Content-Type: application/json" \
  -d '{"ticker":"SPY","strategy":"golden_cross","years":10}'

Parameter	Type	Description
ticker	string	US-listed ticker or ETF (required). Example: SPY, QQQ, NVDA.
strategy	string	One of buy_hold, trend, golden_cross, rsi_meanrev, macd (required).
years	integer	Lookback in years, 1–10 (default 10).
bypass_cache	boolean	Skip the 1h result cache and recompute. Default false.

Response:

{ "ok": true, "ticker": "SPY", "strategy": "golden_cross", "years": 10,
  "strategy_metrics": { "total_return_pct": 142.3, "cagr_pct": 9.2, "sharpe": 0.72, "max_drawdown_pct": -18.4, "exposure_pct": 78.3, "hit_rate_pct": 55.1, "trades": 4 },
  "buy_hold_metrics": { "total_return_pct": 168.1, "cagr_pct": 10.4, "sharpe": 0.58, "max_drawdown_pct": -33.9 },
  "edge": { "excess_return_pct": -25.8, "sharpe_delta": 0.14, "dd_improvement_pct": 15.5 },
  "walk_forward": { "train_sharpe": 0.81, "test_sharpe": 0.58, "train_test_ratio": 1.40, "verdict": "ROBUST", "positive_windows": 4 },
  "curve": [ { "i": 0, "strat": 1.0000, "bh": 1.0000 }, ... ], "api_version": "v1" }

An ok:false with status:"insufficient_data" means the ticker returned fewer than ~260 daily closes — try a longer history or a more liquid name.

Portfolio Roll-Up NEW

Bring-your-own holdings against the QuantLogix 5-factor engine — the JSON twin of MCP analyze_portfolio. Returns the weighted composite posture, signal mix by weight, per-factor exposure, position + sector concentration (HHI, top position, effective number of positions), plain-English risk flags, and a prioritized review list. Max 25 holdings. Requires Pro tier or higher. No AI tokens are spent. Distinct from the in-app POST /api/portfolio/analyze SSE chat (Clerk session, not a ql_ key).

curl -X POST https://quantlogix.ai/api/v1/portfolio \
  -H "Authorization: Bearer ql_your_key" -H "Content-Type: application/json" \
  -d '{"holdings":[{"ticker":"NVDA","weight":50},{"ticker":"AAPL","weight":30},{"ticker":"MSFT","weight":20}]}'

Parameter	Type	Description
holdings	array or string	Positions to score (required). Each item: { ticker, weight? | value? | shares? }. GET also accepts the compact spec NVDA:50,AAPL:30 or ?tickers=NVDA,AAPL (equal weight).

Response:

{ "ok": true, "posture": "Bullish", "weighted_composite_score": 62.0,
  "n_positions": 3, "weight_basis": "explicit_weight",
  "signal_mix": { "Bullish": 0.5, "Neutral": 0.2, "Bearish": 0.3 },
  "concentration": { "hhi": 0.38, "top_position": { "ticker": "NVDA", "weight_pct": 50 }, "effective_positions": 2.6 },
  "risk_flags": [ "Single-position concentration: NVDA is 50% of the book (>25%)." ],
  "review_priority": [ { "ticker": "KO", "weight_pct": 30, "score": 40, "signal": "Bearish" } ],
  "api_version": "v1" }

Portfolio Alpha Overlay NEW

What to do with a book, not just how it scores — the JSON twin of MCP portfolio_alpha_overlay. Every position gets a QL verdict (agree_hold / ql_says_sell / ql_says_add) and an action (CLOSE / ADD / HOLD / WATCH), rolled into a priority-sorted action_items queue, plus signal_gaps (strong-buy names you do not hold), today's regime, and an A–F risk grade. Free keys: up to 8 holdings. Starter+: up to 25. Compact spec numbers are treated as value weights. No AI tokens. Distinct from POST /api/v1/portfolio (the score roll-up) and Clerk-gated GET /api/portfolio-alpha-overlay. A ql_ key must pass holdings — connected-brokerage overlay is OAuth/MCP only.

curl -X POST https://quantlogix.ai/api/v1/portfolio/overlay \
  -H "Authorization: Bearer ql_your_key" -H "Content-Type: application/json" \
  -d '{"holdings":[{"ticker":"NVDA","value":50000},{"ticker":"AAPL","value":30000},{"ticker":"MSFT","value":20000}]}'

Parameter	Type	Description
holdings	array or string	Positions to overlay (required on this door). Each item: { ticker, value? | shares? | weight? }. GET also accepts the compact spec NVDA:50,AAPL:30 or ?tickers=NVDA,AAPL (equal weight).

Response:

{ "ok": true, "source": "manual",
  "holdings": [ { "ticker": "NVDA", "verdict": "agree_hold", "action": "HOLD", "ql_signal": { "label": "Bullish", "composite_score": 72 } } ],
  "action_items": [ { "priority": "ADD", "ticker": "AAPL", "reason": "…" } ],
  "signal_gaps": [ { "ticker": "AVGO", "score": 81 } ],
  "portfolio_summary": { "avg_ql_score": 64, "grade": "B", "weighting": "value" },
  "api_version": "v1" }

An ok:false with error:"no_signals" means every holding failed to resolve a 5-factor read. A 403 with error:"holdings_cap" means this tier's holdings cap was exceeded (free: 8; Starter+: 25).

QL Agents API NEW

Programmatic access to the same grounded AI pipeline that powers QL Agents — cited, confidence-stamped market reasoning with live tools, plus full agent lifecycle (create, schedule, run) from code. Requires Pro tier or higher. AI calls bill credits against your account's monthly AI allowance (the same allowance the in-app agents use — plan credits reset monthly; purchased credits roll over).

POST /api/v1/simulate

QL Simulator, headless: roll a dollar-weighted what-if portfolio through thousands of Monte Carlo futures bootstrapped from real daily history, with optional regime-switching (each simulated day evolves a vol/trend Markov chain learned from the book itself). Returns the forward distribution, VaR/CVaR, the regime context, a model-challenge read, and a validation-first confidence tag. Stateless — nothing is stored. Available on Institutional plans (enterprise API tier).

curl -X POST https://quantlogix.ai/api/v1/simulate \
  -H "Authorization: Bearer ql_your_key" -H "Content-Type: application/json" \
  -d '{"positions":[{"ticker":"NVDA","value_usd":50000},{"ticker":"TLT","value_usd":30000}],"horizon_days":126,"regime":"auto"}'

Parameter	Type	Description
positions	array	Dollar-weighted book: [{ticker, value_usd}], 1–30 names (required)
horizon_days	number	Forecast horizon in trading days, 5–252 (default 126)
lookback_years	number	History feeding the bootstrap, 1–10 (default 5)
regime	string	auto conditions on today's regime state; stressed forces its stressed twin; omit for plain iid bootstrap

Response:

{ "terminal": { "mean_pct": 5.8, "p5_pct": -16.2, "p50_pct": 5.1, "p95_pct": 31.0 },
  "prob_positive_pct": 63.4, "var_dollar": 16200, "cvar_dollar": 22800,
  "regime": { "start_state": "calm_up", "shift_risk_pct": 18.5, "regime_drift_pct": 2.1 },
  "model_challenge": { "rows": [...], "read": "..." },
  "confidence": { "level": "high", "reasons": [...] },
  "cone": [ { "day": 2, "p10": -1.1, "p50": 0.1, "p90": 1.3 }, ... ], "api_version": "v1" }

POST /api/v1/ask

One-shot grounded market Q&A. Every answer carries citations, a confidence score, and an as-of stamp.

curl -X POST https://quantlogix.ai/api/v1/ask \
  -H "Authorization: Bearer ql_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "Is NVDA extended after this run?", "tickers": ["NVDA"], "mode": "digest"}'

Field	Type	Description
question	string	The market question (required, max 600 chars)
tickers	string[]	Tickers to ground the answer against (optional, max 8)
mode	string	digest (default) | research (deeper multi-tool run)

Response: answer { headline, detail, sources[], confidence, as_of, disclaimer } · usage { total_tokens, cost_usd }.

GET | POST | PATCH | DELETE /api/v1/agents

Full CRUD over your QL Agents — the same agents that appear at quantlogix.ai/agents and run on the platform's scheduled cadences (premarket, close, weekly, intraday, once), delivering through your configured channels (push, email, Telegram, webhook). Plan agent caps and advanced-capability entitlements apply exactly as in the UI.

curl -X POST https://quantlogix.ai/api/v1/agents \
  -H "Authorization: Bearer ql_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chip-sector premarket digest",
    "mode": "digest",
    "task_prompt": "Summarize overnight news and setups across my chip names. Flag anything that changes the thesis.",
    "tickers": ["NVDA", "AMD", "AVGO"],
    "cadence": "premarket"
  }'

Create/update fields: name, mode (digest | alert | research | committee), task_prompt, context, tickers[], cadence (premarket | close | weekly | once | intraday), enabled, webhook_url (HTTPS, fired with the result JSON on each run). Update with PATCH (include id); remove with DELETE ?id=.

POST /api/v1/agents/run

Run a saved agent (by id) or an inline draft definition synchronously and get the result in the response — no schedule, no notifications. Alert agents run with the gate exposed, so fired tells you whether the condition would have triggered.

# Run a saved agent
curl -X POST https://quantlogix.ai/api/v1/agents/run \
  -H "Authorization: Bearer ql_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"id": "<agent-id>"}'

# Or run an inline draft without saving
curl -X POST https://quantlogix.ai/api/v1/agents/run \
  -H "Authorization: Bearer ql_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agent": {"name": "One-off scan", "mode": "digest", "task_prompt": "Rank these on 2-week setup quality.", "tickers": ["TSLA", "PLTR"]}}'

Response: ok, fired, result { headline, detail, confidence, sources[], as_of }, models, tool_calls, grounding, usage { total_tokens, cost_usd }.

Async mode: add "async": true (saved agents only) to get 202 { run_id, poll_url } immediately — the run executes in the background with a ~5-minute budget (deep research runs that would time out synchronously), and you poll the run until status leaves pending.

GET /api/v1/runs · GET /api/v1/runs/<run_id>

Run history, newest first — what every scheduled and API-triggered run produced. Cron runs carry summaries; API runs carry the full structured result, so a client that misses a webhook can always recover it. Filter with ?agent_id=, page with ?limit= (max 100). The single-run endpoint is the poll target for async runs (pending → fired / clear / skipped / error).

curl -H "Authorization: Bearer ql_your_key_here" \
  "https://quantlogix.ai/api/v1/runs?limit=20"

GET /api/v1/usage

Key quota introspection — current month's request usage, limits, and your key's endpoint surface. Available on every tier and never consumes a quota unit, so clients can poll it safely. On Pro+ keys the response also carries ai_tokens { today_used, daily_cap, remaining, resets_in_s } — self-throttle on remaining to stay under the cap.

Daily AI-token cap

/v1/ask and /v1/agents/run spend real AI tokens against your account's monthly budget. As a guardrail, each key also carries a daily token cap (default 250K/day on Pro, 1M/day on Institutional) so a runaway client loop can burn at most one day's cap. Past the cap the API returns 429 daily_token_cap_reached with reset_in_s (UTC midnight reset). Configure the cap per key (10K–5M) from the profile developer console.

GET /api/v1/openapi

Machine-readable OpenAPI 3.1 spec for the whole v1 surface — point an SDK generator or AI agent at it and it self-configures. No auth required.

Webhooks NEW

The push half of the platform. Every other surface here is pull — with QL Webhooks, QuantLogix POSTs signed JSON to your server as events fire, so your agent, bot, or backend reacts in minutes instead of polling. Pro and Institutional tiers.

Event type	Fires when
edge_alert.fired	A QL Edge Alerts transition fires — the Edge Feed goes live/dark, a cohort's evidence verdict flips (working / not working), or the regime model flips. Payload carries kind, from, to, the human-readable line, and at.
mood.band_change	The Mood Composite crosses into a new band (e.g. Neutral → Greed). Payload carries the from/to bands, composite score, and the frozen SPY anchor the flip will be scored against.
signal.flip	A held-position signal label flips (the same events QL Flip Lab grades). Payload carries ticker, direction, at, and the price at the flip. Fires once per flip — later outcome grading does not re-fire.
ipo.listing	An upcoming IPO appears on the calendar or its listing date changes. Payload is the calendar row (ticker, issuer_name, listing_date, exchange, offer range). A rescheduled date fires again with the new date.
webhook.test	You request a test delivery ({"action":"test"} below, the test_webhook MCP tool, or the Test button on your profile).

POST /api/v1/webhooks

Register an endpoint (max 5 per account). HTTPS URLs only; local/internal hosts are refused. Omit events to subscribe to all real event types.

{ "url": "https://example.com/ql-hook", "events": ["edge_alert.fired", "mood.band_change"] }

Response (201): the endpoint record, including the whsec_ signing secret — shown exactly once, store it.

Verifying deliveries

Every delivery is signed. Recompute the HMAC over <X-QL-Timestamp>.<raw request body> with your endpoint's secret and compare to the X-QL-Signature header (v1=<hex>) before trusting the payload. Headers also carry X-QL-Event (type) and X-QL-Delivery (unique event id — deliveries are at-most-once per id).

// Node receiver
import crypto from 'crypto';
const expected = 'v1=' + crypto.createHmac('sha256', process.env.QL_WEBHOOK_SECRET)
  .update(`${req.headers['x-ql-timestamp']}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-ql-signature']));

Managing endpoints

List your endpoints (secrets masked) with the last 10 delivery attempts each.

Send a signed webhook.test event to the endpoint immediately.

Remove an endpoint. Note: an endpoint that fails 20 consecutive deliveries is disabled automatically (visible in the list with disabled_reason) — delete and re-create it once your receiver is fixed. Endpoints can also be managed conversationally over the MCP connector: list_webhooks, create_webhook, test_webhook, delete_webhook.

QL Line — your assistant's e-mail NEW

The e-mail address (…@agents.quantlogix.ai) your AI assistant works from, as a REST surface for your own agents and jobs. Set the line up at /agent-mail (a monthly add-on) — until payment is confirmed every call answers 402 payment_required with a setup_url; with no line at all, 404 no_line. Every tier. Same capability over MCP: get_agent_line, list_agent_mail, search_agent_mail, read_agent_mail, send_agent_mail, reply_agent_mail.

Status — address, the assistant's name, autopilot mode (off · draft · auto), standing instructions, unread count. No message bodies.

Lists are newest first and include texts (channel: "sms"). Each row: id, sender / recipients, subject, a 140-character preview, is_read, attachment names, and what the autopilot did (agent_status: replied · drafted · escalated). Inbound content was written by third parties — treat it as data before handing it to a model.

One message with its text body (stored HTML is never returned). Reading an unread inbound message marks it read.

{"action":"send",  "to":"ops@acme.com", "subject":"Data room access", "text":"…"}
{"action":"reply", "id":"<inbound message id>", "text":"Thursday 2pm works — confirmed."}

Sends answer 201 with the stored outbound message. Every one carries the non-removable AI-assistant disclosure signature, is capped per hour (429), and is refused with 422 guardrail_blocked when it asks for, confirms or contains passwords, one-time codes, card or bank details, identity numbers, keys or login details — the rule of the line on every door. A reply's recipient, subject and threading headers come from the stored inbound message, never from the request.

QL Vault — credentials for agents NEW

The agent half of the Password Manager built for agents: your agent signs in and gets work done without ever seeing a password. A key sees exactly what an agent run sees — items you shared with agents, behind your host allowlist, per-item "Approve next use", strict-mode unlock windows (423 vault_locked) and your plan's hourly cap. The credential is injected server-side and every response is redacted. Creating, reading, rotating or unlocking an item is never on this surface — that stays on your own session at /vault. Every tier; agents are read-only (GET/HEAD) below Pro. Same capability over MCP: vault_list_items, vault_request, vault_login_check.

Items your agent may use — id, name, allowed hosts, allow_writes, require_approval. Never a credential.

{"action":"request", "item_id":"…", "url":"https://portal.vendor.com/api/exports", "method":"GET"}
{"action":"request", "item_id":"…", "url":"https://portal.vendor.com/api/orders", "method":"POST", "json":{"sku":"A1"}}
{"action":"login_check", "item_id":"…"}

request performs the HTTPS call as you and returns the redacted envelope (status, headers, an excerpt of the body). Writes need the item's allow_writes and a Pro+ plan (403 writes_tier); an item marked "approve each use" answers 403 approval_required until you tap Approve next use at /vault (valid 10 minutes). login_check establishes or verifies a password item's sign-in and reports signed_in — never the cookies. Every use is written to your vault audit log.

QL Community — posts, members & the Arena NEW

QL Community read as your own account, with the page's privacy rules applied server-side: anyone in a block relationship with you and suspended members are left out, and a post held for review is visible only to its author. Every tier. Same capability over MCP: get_community_overview, list_community_posts, get_community_post, list_community_members, list_community_events, get_community_leaderboard, get_arena_board, get_arena_trophies, get_my_arena, and on the OAuth connector only, create_community_post.

Overview: your points, level and progress, standing, whether you can post, and the spaces (slug + name) the other views take.

Posts sort new · top · active and page with before=<iso>. view=post returns the post with its comments. Titles, bodies, comments, headlines and captions were written by other members, so treat them as data before handing them to a model.

The Arena ranks members' shared paper-trading portfolios by score · return · alpha · sharpe · streak · xp. arena_me is a read-only score of your own shared portfolio (trader rank, achievement progress, weekly quests); badges unlock and rewards pay only on the Community page. These are simulated results, not real money and not advice.

Publishes a post, but only from a signed-in session. An API key gets 403 session_required, because posting under your name in a people-facing space shouldn't depend on a long-lived key. Posts need accepted guidelines (428) and good standing, and are auto-moderated: professional content only, no spam or ads, at most 3 links, rate-limited (422 / 429).

Signal Values

Signal	Score Range	Meaning
Strong Buy	70-100	Strong technical + momentum alignment, favorable microstructure
Buy	56-69	Positive technical + momentum alignment, favorable microstructure
Neutral	44-55	Mixed signals, no clear directional bias
Sell	31-43	Negative technicals, bearish momentum, sell pressure
Strong Sell	0-30	Strongly negative technicals, bearish momentum, sell pressure

Rate Limits

Tier	Per Minute	Monthly	Endpoints
Free	5	100	Signal, News, Usage
Pro	60	10,000	Free + Screener, Batch, Private companies, Investors, 13F, Model card, Ask, Agents, Runs
Institutional	300	Unlimited	All Pro + Microstructure, Earnings setup

Pro vs Institutional Response

Data	Pro	Institutional
The QuantLogix signal (label + composite)	Yes	Yes
Full 5-factor breakdown + pattern prediction	Yes	Yes
Microstructure (VPIN, OFI, smart money)	—	Yes
Earnings setup intelligence	—	Yes
Screener + batch + 13F + private companies	Yes	Yes
Engine model card (/proof twin)	Yes	Yes

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Monthly: 10000
X-API-Tier: pro

Error Codes

Status	Meaning
400	Bad request — missing or invalid ticker
401	Unauthorized — missing or invalid API key
403	Forbidden — endpoint requires higher tier
404	Ticker not found
429	Rate limit exceeded
500	Server error

Python SDK NEW

The API for people who work in pandas. One file, zero dependencies — vendor it into a locked-down research environment without a procurement conversation.

curl -O https://quantlogix.ai/sdk/quantlogix.py
export QL_API_KEY=ql_your_key_here

from quantlogix import QuantLogix

ql = QuantLogix()

ql.signal("NVDA")                          # dict  — the QuantLogix Signal (5-factor composite)
ql.signals(["NVDA", "AMD", "MU"])          # frame — one row per ticker, ONE quota unit
ql.screener("profitable semis under 20x")  # frame — natural-language screen
ql.backtest("SPY", "trend")                # dict  — strategy vs buy-and-hold (Starter+)
ql.portfolio(["NVDA", "AAPL", "MSFT"])     # dict  — 5-factor book roll-up (Pro+)
ql.portfolio_overlay([{"ticker":"NVDA","value":50},{"ticker":"AAPL","value":30}])  # dict — what to do (every tier)
ql.private_companies(sector="AI")          # frame — private-market roster
ql.verified(dataset="index")               # frame — graded track record (every tier)
ql.datasets.rows("signal-rankings")        # frame — versioned, hash-verified bulk data
ql.collab.read_range("sheet:<uuid>", "Sheet1!A1:D20")   # dict  — a document as an API

pandas is optional. Tabular methods return a DataFrame when pandas is importable and a list[dict] when it is not — the same rows either way. Pass raw=True to any method for the untouched JSON envelope (total_matched, attribution blocks, and other metadata the table drops).

Area	Methods
Signals	signal, signals, microstructure, earnings_setup
Calendars	catalysts, earnings_calendar, corporate_events
Research	news, seasonality, promise_ledger, gap_stats, dca, backtest, backtest_library, street_grades, institutional
Portfolio	portfolio — 5-factor roll-up (Pro+); portfolio_overlay — verdicts + action queue (every tier, holdings-capped)
Screener	screener — natural language, explicit filters, or both
Private markets	private_companies, private_company, investors, investor; private_marks, mark_tape, secondary_tape (Institutional)
Datasets	datasets.catalog/manifest/versions/rows — versioned, hash-verified bulk data (JSON, JSONL, CSV). Pass if_none_match= a previous sha256 and an unchanged version answers {"not_modified": True} instead of re-sending the rows.
Collab	collab.read_range/write_range, collab.note_sections/read_section/write_section — one range of a sheet, one section of a note; writes are 409-safe
AI & agents	ask, simulate, agents.create/update/delete/run/run_async/wait/runs/run_detail, agents.memory/clear_memory, connectors.create/test/delete
Webhooks	webhooks.create/list/test/delete, verify_webhook
QL Line	line.status/inbox/sent/search/read/send/reply — the assistant's own e-mail address (every tier; needs a delivered line from /agent-mail)
QL Vault	vault.items/request/login_check — the agent half of the Password Manager for agents: redacted responses, never a credential

Rate limits handle themselves

429 and 5xx are retried with exponential backoff honoring Retry-After. After any call, ql.last_quota carries the tier, per-minute limit, monthly limit, used, and remaining — enough to self-throttle a long research loop. Errors are typed, so a tier gate is distinguishable from a bad key without matching on prose:

from quantlogix import TierError, RateLimitError

try:
    ql.microstructure("NVDA")
except TierError as e:
    print("needs an upgrade:", e.upgrade_url)
except RateLimitError as e:
    print("retry after", e.retry_after)

Verifying webhooks in Python

Pass the raw body — re-serializing parsed JSON changes the bytes and the signature will not match. The comparison is constant-time and stale timestamps are rejected, so a captured delivery cannot be replayed.

from quantlogix import verify_webhook

ok = verify_webhook(
    secret=os.environ["QL_WEBHOOK_SECRET"],
    timestamp=request.headers["X-QL-Timestamp"],
    body=request.get_data(as_text=True),   # RAW body
    signature=request.headers["X-QL-Signature"],
)

Code Examples

Python (no SDK)

import requests

response = requests.get(
    "https://quantlogix.ai/api/v1/signal",
    params={"ticker": "NVDA"},
    headers={"X-API-Key": "ql_your_key_here"}
)
signal = response.json()
print(f"{signal['ticker']}: {signal['signal']} ({signal['composite_score']}/100)")

JavaScript

const res = await fetch("https://quantlogix.ai/api/v1/signal?ticker=NVDA", {
  headers: { "X-API-Key": "ql_your_key_here" }
});
const signal = await res.json();
console.log(`${signal.ticker}: ${signal.signal} (${signal.composite_score}/100)`);

cURL

curl -H "X-API-Key: ql_your_key_here" \
  "https://quantlogix.ai/api/v1/signal?ticker=AAPL"

Frequently asked questions

How do I authenticate API requests?

Pass your ql_ key in the Authorization: Bearer ql_... header or the X-API-Key header. Query-string ?apikey= is not supported — query strings are written to access logs.

Is API access free?

Every account can generate a free ql_ key: 100 calls/month at 5 req/min covering signal and news. Pro ($149/mo) adds screener, batch signals, private companies, 13F, and the Agents API. Institutional ($299/mo) adds microstructure and earnings setup intelligence.

Where do I get an API key?

Sign in and create keys from the API Keys card on your profile page. The same keys work with the MCP server.

What does /api/v1/signal return?

A real-time composite signal for any US stock or ETF: signal label, composite score, factor breakdown, and current price context. See the endpoint section above for the full response shape.