API reference

Start here

Most members never call the API directly — they paste the prompt from their setup email into ChatGPT Work or Claude Cowork and name a ticker. The prompt carries the key and the calling rules. This page is for people wiring it up themselves.

Authentication

Send your key in the X-API-Key header. Keys start with qd_. Paid keys are issued at checkout (first 3 days of a subscription are a free trial); a free evaluation key — 10 successful calls per UTC day, no card, no account — arrives by email when you POST an address to /v1/access/free-key.

curl -H "X-API-Key: qd_your_key" \
  "https://api.maddog.finance/v1/brooks/ES=F"

# free evaluation key, delivered by email:
curl -X POST "https://api.maddog.finance/v1/access/free-key" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Standard ChatGPT and Claude web or mobile chat cannot attach a custom header, so they cannot call this API. Work and Cowork modes can.

MCP

The API is also a Model Context Protocol server — stateless streamable HTTP at https://api.maddog.finance/mcp — so any MCP-capable agent (Claude Code, Claude Desktop, Cursor, and friends) can wire MADDOG in as three tools: price_action_read, get_scoreboard and request_free_key. The scoreboard tool is free and keyless; the read grants one anonymous first look per day, and the free-key tool gets an agent its own allowance without leaving the conversation.

claude mcp add --transport http maddog https://api.maddog.finance/mcp

# with a key:
claude mcp add --transport http maddog https://api.maddog.finance/mcp \
  --header "X-API-Key: qd_your_key"

The endpoint is stateless: one JSON-RPC message per POST, plain-JSON responses, no session to manage. Authorization: Bearer qd_… also works there for clients that only speak bearer auth.

GET /v1/brooks/{symbol}

The main read. One fast signal and one slow one: the current window’s first range breakout, which settles within 10 bars, and the day-type distribution for the session, which settles at the close.

Symbols

URL-encode the symbol. ES=F becomes ES%3DF. Never put a slash in a symbol.

Query: window

asia and gap apply to 24-hour instruments only — futures, FX and crypto.

What comes back

events[]

The window's first qualifying range breakout, if one has fired: price closing outside the high–low of the immediately preceding 10 bars when that range is no wider than 0.5× ADR5. At most one entry — one window, one day, one breakout, which is exactly the rule the reference rates were measured under. Empty array means none yet; that is a real answer, not an error.

events[].reference

The frozen ES failure rates for that exact production definition in that exact window, measured on five-minute bars from 2010–2026 with the eligible event count attached.

events[].conditional_estimate

Calibrated probability this particular breakout closes back through its own level within 10 bars, conditioned on its own rolling context. The original model used a zero-shot NQ protocol; its production ADR5 port was checked on NQ 2023+: AUC 0.646, calibration error 5.1%, n=2,637.

events[].outcome_so_far

Whether the 10-bar outcome has resolved yet, and what it was — including when the estimate turned out wrong. An unresolved event is still open; do not read it as a completed result.

day_type

Five-class distribution over how this session resolves, from the model trained for the current window: 66% top-1 over a complete day session against a 37% majority-class baseline. The Asian window has its own model on its own label taxonomy — the two accuracy sets are not comparable. The gap window has none, and it says so.

day_type.analysis.confidence

How much to trust that distribution, from two independent signals: the model's own conviction and how consistently the most similar past sessions resolved. Both high was right 95% of the time, both low 41%, against the model's own 66%. Day session only.

day_type.analysis.will_extend

Whether the session's own high or low gets taken out before the close, as a base rate for the day type the model just read, carried with today's two levels. Read at the three-hour mark it was right 69% of the time against 48% for ignoring the day type, and 81% when the model's conviction was above 60% — held out on 576 later sessions the model never saw. Reach only: it carries no distance past the level, and it is withheld on the two day types whose samples are too thin to stand behind. Day session only.

quote / volatility_base

Last price and the 5-day average daily range, so a move can be sized against the instrument's own volatility.

window_is_live

True while the window is still printing bars. False means the window is complete.

POST /v1/brooks/backtest

Replays the same breakout read across a bar series you supply, one day at a time, so you can measure the estimate against your own history — on your instrument, where it has not been validated. Same code path as the live read, and the model only ever sees bars up to each event, so there is no look-ahead. The first three days establish the volatility base and cannot be scored.

curl -X POST -H "X-API-Key: qd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"bars": [[1709300000, 5000.0, 5004.5, 4998.2, 5002.1, 12400], ...]}' \
  "https://api.maddog.finance/v1/brooks/backtest"

Each bar is [timestamp, open, high, low, close, volume]. One call is one charge; a call that fails validation is not charged.

Errors

Errors are application/problem+json with a machine-readable error_code, a retryable flag and a message_for_your_human your agent can relay verbatim. On 401, 402, 403 or 429, stop — never retry a billing or access error.

Bars are delayed five minutes. A window that is still printing is marked window_is_live: true; do not report it as a completed session.