PreReason API Documentation

Complete API reference for the PreReason market context API. Financial data optimized for AI agents, delivered in markdown or JSON format.

Authentication

All API requests require an API key. Pass it in one of these headers:

X-API-Key: YOUR_KEY (recommended)
Authorization: Bearer YOUR_KEY

Example: curl -H "X-API-Key: YOUR_KEY" https://api.prereason.com/api/btc

Get your free API key — no credit card required.

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

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: signal direction (bullish/bearish/neutral), confidence score (0-100), 7d/30d/90d trend changes, percentile ranking against historical distribution, cross-asset correlation coefficients, and narrative text (Pro tier).

JSON responses include the same data in structured key-value format with typed fields.

Rate Limits

Free: 60 requests/hour, 500/day — 6 briefings, rolling 30-day data
Basic ($19.99/mo): 120 requests/hour, 2,000/day — 12 briefings, data from Jan 2025
Pro ($49.99/mo): 300 requests/hour, 5,000/day — all 18 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.

Remote MCP endpoint: https://api.prereason.com/api/mcp

5 tools available: get_context, get_metric, list_briefings, list_metrics, get_health

Available Briefings

btc.quick-check (free) — Quick Check: Quick directional read on Bitcoin price and net liquidity with their 30-day correlation
btc.context (free) — BTC Context: Bitcoin price, mining health, and liquidity overview with 7-day and 30-day trend signals
macro.snapshot (free) — Macro Snapshot: Fed balance sheet, M2 money supply, full Treasury yield curve (2Y/10Y/30Y), 10Y breakeven inflation, dollar index, and composite net liquidity with trend direction across all four
cross.correlations (free) — Correlation Check: How Bitcoin correlates with equities, volatility, and the dollar across 9 metric pairs (30-day window)
btc.pulse (free) — BTC Pulse: Quick price action check - price, 24h change, dominance
btc.grid-stress (free) — Grid Stress: Mining network health - block production speed and upcoming difficulty adjustment forecast
btc.momentum (basic) — BTC Momentum: Multi-timeframe BTC momentum (7d/30d/90d) with percentile rankings, 200-day moving average distance, 24h volume, 30d volume Z-score (confirmation/non-confirmation overlay), hash-rate, dollar strength, and net-liquidity backdrop
macro.liquidity (basic) — Liquidity Momentum: Fed balance, Treasury General Account, M2 money supply, and composite net liquidity tracking with 7d/30d/90d trend changes and YTD percentile rankings
btc.on-chain (basic) — On-Chain Health: Bitcoin network deep-dive - hash rate, difficulty, transaction count, volume, and active addresses with trends
cross.breadth (basic) — Market Breadth: Risk appetite 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, and stress signals
btc.full (pro) — Full Context: Full Bitcoin analysis - price, macro overlay, momentum, percentiles, correlations, and narrative text
btc.factors (pro) — Factor Attribution: Rule-based "why is Bitcoin moving" with contributing macro and on-chain factors
cross.regime (pro) — Regime Check: Market regime classification (risk-on, risk-off, accumulation, distribution) with divergence alerts, stablecoin sentiment, and central-bank policy spreads
fx.liquidity (pro) — FX Liquidity: Dollar and currency environment - EUR/USD, CNY/USD direction with net liquidity correlation
btc.energy (pro) — Energy Cost Index: Mining economics - production cost model, natural gas input costs, and energy margin pressure
btc.treasury (pro) — Treasury Holdings Intelligence: Corporate Bitcoin treasury holdings - accumulation trends from SEC filings and CoinGecko
btc.etf-flows (basic) — BTC ETF Flows: Spot BTC ETF flow read: net daily flows, aggregate AUM (~$99B real, 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

Browse all briefings | Browse all metrics