Complete API reference for the PreReason market context API. Financial data optimized for AI agents, delivered in markdown or JSON format.
Authentication
Briefings and metric readings need an API key (or, on the short URLs, metric readings and company routes, an x402 payment per call); the catalogue and health check need none. Pass a key in one of these headers:
An agent can get a key from inside its session: POST https://api.prereason.com/api/agent/claims starts a claim, the person it works for approves one link, and the key reaches the agent when it polls. auth.md has the whole flow.
Primary Endpoint: GET /api/context
Returns a pre-reasoned market briefing for the requested domain.
Parameters
briefing (required) — Briefing ID, e.g. btc.quick-check, macro.snapshot, btc.full
format (optional) — markdown (default) or json
date (optional) — YYYY-MM-DD for historical data (Basic+ tiers)
Example: GET /api/context?briefing=btc.context&format=markdown
Short URL Shortcuts
GET /api/btc — btc.quick-check briefing
GET /api/macro — macro.snapshot briefing
GET /api/fx — fx.liquidity briefing
GET /api/btc/treasury — btc.treasury briefing
Company Briefings
One listed company per call, each figure dated and sourced: GET /api/context?briefing=equities.company/<company> with a key on the plans that read it, or GET /api/companies/<company> paid per call with x402 and no key. 3,002 USA company briefings as of 2026-10-07, 1,546 Japanese company briefings as of 2026-10-06, 2,533 Korean company briefings as of 2026-10-07, 232 Indian company briefings as of 2026-10-07, 464 company briefings for companies filing in the UK as of 2026-10-15 and 822 company briefings for companies filing in 11 European countries as of 2026-10-15.
Other Endpoints
GET /api/metrics — List all available metrics with current values
GET /api/metrics/{name} — Get a specific metric with trend analysis
GET /api/health — API health check and data pipeline status
Response Format
Markdown responses include: a tag on each metric (Bullish, Bearish or Neutral on crypto native metrics such as Bitcoin and Ether; on every other metric Above-Trend, Below-Trend or At-Trend, where the value sits against its trend), confidence score (0-100), 7d/30d/90d trend changes, percentile ranking against historical distribution, and cross-asset correlation coefficients.
JSON responses include the same data in structured key-value format with typed fields.
Rate Limits
Free: up to 100 calls a day, no more than 30 in an hour, 6 briefings, rolling 30-day data
Basic ($19.99/mo, the founding price for the first 100 subscribers, $50 a month for everyone after): up to 7,000 calls a day, no more than 500 in an hour — 20 briefings, up to 3 years of history, Bitcoin from Jan 2025
Pro ($49.99/mo, the founding price for the first 50 subscribers, $150 a month for everyone after): up to 35,000 calls a day, no more than 2,000 in an hour — all 33 briefings, full historical data
Enterprise: Custom limits and SLA
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
MCP Server Integration
Install the PreReason MCP server for native tool access in Claude Desktop, Claude Code, Cursor, and Windsurf.
Install: npx -y @prereason/mcp
Set environment variable PREREASON_API_KEY to your API key.
btc.quick-check (free) — Quick Check: Quick check of Bitcoin's price and net liquidity, each with its recent changes, and their 30-day correlation
btc.context (free) — BTC Context: Bitcoin price, mining health, and liquidity overview with 7-day and 30-day trends
macro.snapshot (free) — Macro Snapshot: Fed balance sheet, M2 money supply, Treasury yields at 2Y, 10Y and 30Y, 10Y breakeven inflation, dollar strength (the UUP ETF), and composite net liquidity with trend direction across all four, plus global central-bank balance-sheet overlay (BOJ total assets, ECB total assets, Eurozone M3) for cross-region liquidity context; and the latest US releases as published: the Employment Situation (nonfarm payrolls and the unemployment rate), the Consumer Price Index and the weekly jobless claims, each with what it revised and the next release date
cross.correlations (free) — Correlation Check: How Bitcoin correlates with equities, volatility, and the dollar across 10 metric pairs (30 and 90 day windows)
btc.grid-stress (free) — Grid Stress: Mining network health: block production speed against the 10-minute target and the direction it points for the next difficulty adjustment, with hash rate and the hash ribbon
btc.momentum (basic) — BTC Momentum: Bitcoin momentum over 7, 30 and 90 days with percentile rankings, distance from the 200-day moving average, 24h volume and its 30-day Z-score, hash rate, dollar strength, net liquidity, and BTC perpetual futures positioning (funding rate and open interest)
macro.liquidity (basic) — Liquidity Momentum: One state of US dollar liquidity (adding, steady or draining, from net liquidity's 30 day change) with its drivers, their sources and known times, bank reserves from the Federal Reserve Board's H.4.1, and repo against the Fed's range; plus Fed balance, Treasury General Account, M2 money supply, composite net liquidity tracking with 7d/30d/90d trend changes and percentile rankings, NY Fed System Open Market Account (SOMA) total holdings, and daily reverse-repo take-up
macro.auctions (basic) — Treasury Auction Calendar and Dynamics: Who bought at the latest auction of each Treasury note and bond maturity: size, high yield, bid-to-cover and the shares of primary dealers, direct and indirect bidders, each against that maturity's own prior auctions; then the auctions announced and scheduled next; then Treasury's newest buyback operations as its record states them (maturity bucket, maximum, par offered and accepted).
macro.calendar (basic) — Macro Calendar: Releases, Decisions and Auctions: The scheduled dates ahead and the latest US releases as they came out: the next Producer Price Index, retail sales, GDP and Personal Income and Outlays releases, the FOMC minutes, the Federal Reserve's and the ECB's next decisions, Treasury's next quarterly refunding release and the Treasury coupon auctions of the week ahead on Treasury's tentative schedule, or the next one when the week has none, each dated from its publisher's own calendar (dates only, no figures from them); and the US Employment Situation, Consumer Price Index and weekly initial claims as release state: for each, the latest release and when it came out, its headline figures within that one release with each figure's estimate (first, second, advance, revised), what the release revised, and the next scheduled release, all from the publishers' own figures with every version kept. Beside it the federal funds rate, the days to the next Treasury auction, euro area HICP and the BoJ policy rate.
cross.ai-compute (pro) — AI Compute and Power Chain: The AI compute and power chain: Korea's semiconductor exports for the first 20 days of the month as Korea Customs Service states them (the change on the same days a year earlier and the share of all exports), average US grid demand over the newest 7 days for the Lower 48, ERCOT and PJM against the same dates a year earlier and the trailing 365 days against the 365 before (PreReason's calculation from EIA-930 daily figures), the AI hosting agreements Bitcoin miners announced in their own SEC current reports (megawatts, customer, term and contracted revenue, each naming its filing), and contracted hosting revenue per gross megawatt per year beside mining revenue per gross megawatt at the current hashprice, and four companies' capital expenditure for their newest quarter, each as its own company briefing serves it from its SEC filings, with the change on the year
macro.rates (pro) — Yield Curve and Breakeven Inflation: Treasury par yield curve at every maturity, 1 month to 30 years, breakeven inflation at 5Y and 10Y, 5y5y forward inflation expectation, the 10Y-2Y spread, the 10Y-3M recession-indicator spread, Germany 10Y Bund as Eurozone long-end anchor for cross-region rate comparison, France 10Y and its spread over Germany (monthly averages from the ECB), and the latest FOMC statement: decision, vote, dissents and wording changes
btc.on-chain (basic) — On-Chain Health: Bitcoin network deep-dive: hash rate, difficulty, transaction count, transaction volume and active addresses, with their recent changes
cross.breadth (basic) — Market Breadth: Breadth across S&P 500, Nasdaq, and small caps with Bitcoin correlation for each
btc.miner-survival (basic) — Miner Survival Index: Miner profitability check: revenue per hash, production cost tiers, price against production cost, the hash ribbon and block pace, with percentile ranks in their own history
btc.full (pro) — Full Context: Full Bitcoin context: price, macro overlay, momentum, percentiles, correlations, and a plain language summary written by fixed rules
btc.factors (pro) — Factor Attribution: Bitcoin's price beside the factors a fixed set of rules reads with it: macro (Fed balance sheet, Treasury account, net liquidity, the dollar, the 30-year Treasury yield), markets (the S&P 500 fund and a long Treasury fund), on-chain (hash rate, volume), BTC perpetual futures positioning (funding rate and open interest), and 30-day at-the-money implied volatility
cross.regime (pro) — Regime Check: Market regime classification (expansion, contraction or transition) with divergence alerts, USDT dominance, central-bank policy spreads, and global central-bank balance-sheet overlay (BOJ total assets, Eurozone M3, Germany 10Y Bund)
fx.liquidity (pro) — FX Liquidity: Dollar and currency environment: the dollar, EUR/USD and USD/CNY with their recent changes, and their 30-day correlations with net liquidity and Bitcoin's price
btc.energy (pro) — Energy Cost Index: Mining economics: production cost model, natural gas input costs, and how energy input costs sit against their recent trend
btc.treasury (pro) — Treasury Holdings Intelligence: Corporate Bitcoin treasury holdings: changes in holdings from SEC filings and CoinGecko
btc.etf-flows (basic) — BTC ETF Flows: Spot BTC ETF flow read: net daily flows, aggregate AUM (sourced from per-issuer pages), and per-issuer breakdown across iShares Bitcoin Trust (IBIT), Fidelity Wise Origin Bitcoin Fund (FBTC), Grayscale Bitcoin Trust (GBTC), and other approved spot ETFs
commodities.gold (basic) — Commodities Gold: GLD, a gold fund (its share price, not an ounce of gold), and gold's own price per troy ounce as the World Bank's monthly average, with what is said to move them: the 10 year real Treasury rate, the dollar fund (UUP), speculators' positions in COMEX gold futures (CFTC) and the gold miners' funds (GDX, GDXJ), each with its measured relationship to the fund. The Fed's balance sheet, the 10 year yield, the long Treasury fund (TLT) and the fund price ratios give context.
commodities.silver (basic) — Commodities Silver: SLV, a silver fund (its share price, not an ounce of silver), and silver's own price per troy ounce as the World Bank's monthly average, with what is said to move them: the gold fund (GLD), the 10 year real Treasury rate, the dollar fund (UUP), speculators' positions in COMEX silver futures (CFTC), the copper fund (CPER) and the silver miners' fund (SIL), each with its measured relationship to the fund. The fund price ratios give context.
commodities.copper (basic) — Commodities Copper: Copper through a copper futures fund (CPER), speculators' net position in COMEX copper futures (CFTC), the World Bank's monthly copper price, and the dollar and gold funds beside it, each with its measured relationship to the copper fund.
commodities.wheat (basic) — Commodities Wheat: Wheat through a wheat futures fund (WEAT), speculators' net position in CBOT soft red winter wheat futures (CFTC), the World Bank's monthly US wheat price, and the dollar fund and the WTI spot price beside it, each with its measured relationship to the wheat fund.
commodities.energy-basket (pro) — Energy Basket: US oil and gas stocks against the five year norm, with what changed and what comes next: EIA weekly commercial crude stocks and Lower 48 gas storage, each placed against the same week in the prior five years; WTI, Brent and Henry Hub spot prices; the Brent to WTI spread; WTI 30 day realised volatility (computed from EIA spot prices, backward looking); the dates of the next EIA reports.
commodities.oil-producers (pro) — Oil and Its Producers: Crude oil and the covered USA companies EDGAR codes tie to it, side by side: US oil and gas stocks against the five year norm (EIA), WTI and Brent spot, then each integrated major, producer and refiner, and two oil field service companies coded as producers, with its share price, its change over 1, 3 and 12 months beside WTI over the same windows, and the 90 day correlation of its daily changes with WTI, with the id of its own briefing for its filed figures. Each group in order of stored market capitalisation; it describes, it does not rank.
commodities.gold-miners (pro) — Gold and the Miners: The gold fund GLD and the covered USA companies tied to gold by their own annual reports, side by side: the World Bank's monthly gold price as context, then each gold and silver miner and each royalty and streaming company with its share price, its change over 1, 3 and 12 months beside GLD over the same windows, the 90 day correlation of its daily changes with GLD, and the id of its own briefing for its filed figures. GLD is a fund's share price, not the gold price. Each group in order of stored market capitalisation; it describes, it does not rank.
commodities.grains-agribusiness (pro) — Grains and Agribusiness: The wheat futures fund WEAT and the covered USA companies a review of their own annual reports ties to grain, side by side: the World Bank's monthly wheat price as context, then each grain merchandiser and processor, seed and crop nutrient company, farm equipment maker and farmland REIT with its share price, its change over 1, 3 and 12 months beside WEAT over the same windows, the 90 day correlation of its daily changes with WEAT, and the id of its own briefing for its filed figures. WEAT holds futures contracts and is not the wheat price. Each group in order of stored market capitalisation; it describes, it does not rank.
eth.context (basic) — Ethereum Context: Where Ether stands in the market: its price and its global 24 hour trading volume, with that volume's 30 day z score (CoinGecko); its distance from the 200 day average (PreReason's calculation on CoinGecko's daily closes); Lido's stETH APR, its 7 day average; the net positions of leveraged funds and asset managers in CME Ether futures, with open interest (the CFTC's weekly Commitments of Traders); and the funding rate on OKX's ETH perpetual (one venue, named as OKX's).
bonds.context (basic) — US Treasury Holders: Short Form: Who holds Treasuries, in short: foreign investors' net purchases (Treasury's TIC), primary dealers' 13 week change in positions (the New York Fed) and speculators' 10 year note futures position (the CFTC), each against its own history; then the 10 year yield and three bond funds.
bonds.full (pro) — US Treasury Holders: Who holds Treasuries: foreign investors' net purchases (Treasury's TIC), primary dealers' 13 week change in positions (the New York Fed) and speculators' 10 year note futures position (the CFTC), each against its own history; the Fed's own Treasury holdings, debt held by the public and the largest foreign holders; what changed, what would change each label and the next reports; then the 10 year yield and three bond funds.