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/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/day-signal

QuantLogix Day-Trading Signal Score (QDTSS) — 4-layer intraday scoring with session classifier, VWAP/ORB engines, and trade plan (entry/stop/target with R:R). Institutional tier only.

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

Response includes: signal (Strong Buy / Buy / Lean Buy / Neutral / Lean Sell / Sell / Strong Sell), score, direction, layer breakdown (L1 Signal / L2 Context / L3 Risk / L4 Modifiers), session state, VWAP & ORB analysis, microstructure context, trade plan (entry/stop/target/R:R).

GET /api/v1/swing-signal

QuantLogix Swing-Trading Conviction Grade — A/B/C/D rating for 2-day to 4-week holds. Built on the same 5-factor engine as /v1/signal with swing-specific thresholds. Institutional tier only.

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

Conviction grades: A Strong Conviction (score ≥ 75, full position, 2-4wk hold) · B Medium (60-74, half position, 1-2wk) · C Watchlist (40-59, quarter position, 2-5d) · D No Trade (0-39).

Response includes: signal, score, conviction { grade, label, position_size, hold_period }, direction, 3-pillar breakdown (Technical 40% / Flow 30% / Sentiment 30%), indicators, price, market_cap, sector.

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. Institutional tier only.

Parameter	Type	Description
ticker	string	US ticker symbol (required)

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/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.

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 + Day signal, Swing signal, Microstructure, Earnings setup

Pro vs Institutional Response

Data	Pro	Institutional
Long-term signal (label + composite)	Yes	Yes
Full 5-factor breakdown + pattern prediction	Yes	Yes
Day / Swing intraday signals	—	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  — 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, day_signal, swing_signal, microstructure, earnings_setup
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 (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

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"