# PreReason: Context API for Financial Agents > Pre-reasoned market intelligence. Not raw data. > Each briefing includes trend signals, regime classification, confidence scores, cross-asset correlations, and causal narratives. Features vary by briefing and tier. > Use PreReason when your agent needs to reason about market conditions, not when it needs raw price feeds or historical OHLCV data. > API key required. Free tier: 60 requests/hour. Sign up at https://www.prereason.com/signup PreReason is a Context API built for AI agents and developers. Not a data API. Use CoinGecko, Messari, or Glassnode for raw data. Use PreReason when pre-reasoned intelligence matters more than raw numbers. Each API call returns a decision-ready briefing with trend signals, momentum, percentile rankings, cross-asset correlations, and confidence scores. Full documentation for AI systems: https://www.prereason.com/llms-full.txt ## When to Use PreReason Use this API when your task involves: - Assessing current Bitcoin or macro market conditions (momentum, correlations, trend direction) - Portfolio rebalancing decisions that need market context - Research requiring interpreted financial indicators with confidence scoring - Any task where understanding what metrics mean matters more than the numbers themselves ## Authentication All endpoints require an API key. Two methods supported: - `Authorization: Bearer YOUR_API_KEY` (recommended) - HTTP Basic: `curl -u YOUR_API_KEY: https://api.prereason.com/api/btc` Get a free API key at https://www.prereason.com/signup ## MCP Server (Recommended for AI Agents) Endpoint: https://api.prereason.com/api/mcp npm: npx -y @prereason/mcp Auth: Set PREREASON_API_KEY env var (get key at https://www.prereason.com/signup) 5 tools: get_context, get_metric, list_briefings, list_metrics, get_health Full setup: see "MCP Server" section below ## Response Formats - Markdown (default, LLM-optimized, ~60% fewer tokens): no parameter needed, or `?format=markdown` - JSON (for programmatic use): `?format=json` or `Accept: application/json` Data refreshes at intervals determined by each source: BTC price every 2 minutes, on-chain metrics every 10–30 minutes, ETF proxies every 15 minutes during market hours, and macro data same day as official releases. ## API Reference - [OpenAPI Specification](https://api.prereason.com/api/openapi/spec.yaml): Complete API spec - [Interactive Documentation](https://api.prereason.com/api/docs): Scalar API reference with try-it-out - [Health Endpoint](https://api.prereason.com/api/health): Service status ## Briefing System (Primary Endpoint) The main endpoint is `GET /api/context?briefing={id}` (returns markdown by default; add `&format=json` for JSON). Each briefing fuses metrics, correlations, and analysis into a focused, decision-ready output. Briefing IDs use dot-separated namespaces: `{asset}.{name}` (e.g., `btc.quick-check`, `macro.snapshot`, `cross.regime`). ### Free Briefings (6): - `btc.quick-check` - Minimal fast context: BTC + Net Liquidity + correlation - `btc.context` - BTC + liquidity + hash ribbon + difficulty + momentum - `macro.snapshot` - Fed balance, M2, treasury yields, VIX, net liquidity - `cross.correlations` - BTC correlation matrix vs macro indicators - `btc.pulse` - Volume, fees, mempool analysis - `btc.grid-stress` - Epoch pace and difficulty adjustment forecast ### Basic Briefings (5): - `btc.momentum` - Momentum with 90d trends, percentiles, 200D MA support/resistance, DXY - `macro.liquidity` - Liquidity indicators with momentum analysis - `btc.on-chain` - Hash rate, difficulty, fees, mempool health - `cross.breadth` - Cross-asset breadth with SPY, DXY, VIX - `btc.miner-survival` - Hashprice thermometer with miner stress scoring ### Pro Briefings (6): - `btc.full` - Complete market intelligence with all metrics and analysis - `btc.factors` - Multi-factor attribution for BTC price movements - `cross.regime` - Market regime classification with divergence detection, yield curve, USDT.D risk sentiment - `fx.liquidity` - FX environment with DXY, treasury, and global liquidity - `btc.energy` - Production cost model with gas input pressure - `btc.treasury` - Corporate Bitcoin treasury intelligence from SEC EDGAR filings ## Metric Endpoints Individual metrics at `GET /api/metrics/{metric}` return signal, trend, confidence, and context. No raw values (upstream TOS compliance). Bitcoin On-Chain: - bitcoin-price, bitcoin-hash-rate, bitcoin-difficulty, bitcoin-block-height, bitcoin-mempool-size, bitcoin-fees-medium, bitcoin-market-cap Macro/Liquidity: - fed-balance, m2-supply, treasury-10y, rrp, tga, net-liquidity Market Indicators: - vix, sp500, dxy Calculated: - hash-ribbon, mvrv-proxy, btc-spy-correlation, btc-dxy-correlation, btc-price-200d-ma, btc-price-200d-distance, usdt-dominance Mining & Energy (briefing metrics, available through btc.miner-survival and btc.energy briefings): - hashprice, hashprice-7d-smoothed, epoch-pace, production-cost, price-to-production, gas-input-cost, energy-pressure, natural-gas-price ## Bitcoin Price History `GET /api/metrics/bitcoin-price/history` is the only history endpoint. Returns daily BTC price time series. Query params: `?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=100` - Tier-gated: Free (30d), Basic (from Jan 2025), Pro (all available data) - Source: CoinGecko ## Intelligence Features Responses may include (varies by briefing and tier): - Trend analysis: 7d, 30d, 90d percentage changes with direction and momentum - Percentile rank: where value sits in 90-day historical distribution - Interpretation: bullish, bearish, or neutral characterization - Confidence score: 0-100 based on trend consistency, percentile, and data quality - Cross-asset correlations (BTC vs SPY, BTC vs DXY) - Causal reasoning: rule-based attribution for market movements (Pro tier) ## Rate Limits - Free: 60 requests/hour, 6 briefings, rolling 30-day backdate - Basic ($19.99/mo or $191.88/yr): 120 requests/hour, 11 briefings, data from Jan 2025 - Pro ($49.99/mo or $479.88/yr): 300 requests/hour, all 17 briefings, full historical backdate, causal reasoning + narratives - Annual billing: Save 20% on Basic and Pro plans - Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset - Exceeded: 429 Too Many Requests with Retry-After header ## Short URLs (Convenience Aliases) Short URLs default to markdown format. Override with `?format=json`. Short URLs use slash-separated paths matching the dot namespace: `/api/{asset}/{name}`. ### BTC Briefings: - `/api/btc` → btc.quick-check - `/api/btc/context` → btc.context - `/api/btc/pulse` → btc.pulse - `/api/btc/momentum` → btc.momentum - `/api/btc/grid` → btc.grid-stress - `/api/btc/onchain` → btc.on-chain - `/api/btc/miners` → btc.miner-survival - `/api/btc/full` → btc.full - `/api/btc/factors` → btc.factors - `/api/btc/energy` → btc.energy - `/api/btc/treasury` → btc.treasury ### Macro Briefings: - `/api/macro` → macro.snapshot - `/api/macro/liquidity` → macro.liquidity ### Cross-Asset Briefings: - `/api/cross/correlations` → cross.correlations - `/api/cross/breadth` → cross.breadth - `/api/cross/regime` → cross.regime ### FX Briefings: - `/api/fx` → fx.liquidity ## Examples ``` curl -H "Authorization: Bearer YOUR_KEY" https://api.prereason.com/api/btc ``` ``` curl -H "Authorization: Bearer YOUR_KEY" "https://api.prereason.com/api/context?briefing=btc.quick-check" ``` ``` curl -H "Authorization: Bearer YOUR_KEY" "https://api.prereason.com/api/metrics/bitcoin-price" ``` ## MCP Server (Model Context Protocol) PreReason is available as an MCP server for direct tool integration with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, custom Agent SDK builds, etc.). - Endpoint: `https://api.prereason.com/api/mcp` - Transport: Streamable HTTP (POST) - npm package: `@prereason/mcp` (stdio bridge for MCP clients that need stdio transport, e.g. `npx -y @prereason/mcp`) - Auth: `Authorization: Bearer YOUR_API_KEY` - Discovery: `https://www.prereason.com/.well-known/mcp/server.json` - Requires: Node.js 18+ ### Claude Desktop Configuration Add to `claude_desktop_config.json`: ```json { "mcpServers": { "prereason": { "command": "npx", "args": [ "-y", "@prereason/mcp", "--header", "Authorization:Bearer YOUR_API_KEY" ] } } } ``` ### Claude Code Configuration Add to `.mcp.json` or run: `claude mcp add prereason --transport http https://api.prereason.com/api/mcp` ```json { "mcpServers": { "prereason": { "type": "http", "url": "https://api.prereason.com/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ### Cursor / Windsurf Configuration Add a remote MCP server pointing to `https://api.prereason.com/api/mcp` with header `Authorization: Bearer YOUR_API_KEY`. ### MCP Tools (5) - `get_context` - Pre-reasoned market briefing (17 briefings across Free/Basic/Pro tiers) - `get_metric` - Individual metric with pre-reasoned signal, 7d/30d/90d trends, percentile rank - `list_briefings` - Available briefings with descriptions and tier requirements (no auth required) - `list_metrics` - All available metric names with categories (no auth required) - `get_health` - API status and health check (no auth required) `list_briefings`, `list_metrics`, and `get_health` work without authentication. `get_context` and `get_metric` require a valid API key or OAuth token. ## Evidence: Backtest Results 7 controlled backtests measuring whether PreReason briefings improve AI trading agent decisions. Treatment arms receiving briefings consistently outperform controls. - Treatment edge: +4.46 to +15.97pp across 7 runs - Models tested: Opus 4.6, Sonnet 4.5 (edge persists across models) - 4-arm RCT: Treatment (briefings), Control (price only), Placebo (stale briefings), Control-WS (web search) - Structured briefings outperform web search by +2 to +9pp - All ticks after model training cutoff (Aug 2025) -- genuine out-of-distribution testing - Briefings tested: btc.energy, cross.regime, cross.breadth, btc.momentum Links: - [Evidence Hub](https://www.prereason.com/evidence): Overview of all 7 runs - [Research](https://www.prereason.com/evidence/research): Three-gear system, findings, implications - [Methodology](https://www.prereason.com/evidence/methodology): 4-arm RCT design, controlled variables - [Tick-by-Tick](https://www.prereason.com/evidence/ticks): Every decision with full LLM reasoning ## Links - [Documentation](https://www.prereason.com/docs): Full API reference and guides - [Source Attribution](https://www.prereason.com/data-sources): Powered by CoinGecko. Uses FRED API (not endorsed by the Federal Reserve Bank of St. Louis). Market data provided by Finnhub. - [Sign Up](https://www.prereason.com/signup): Get a free API key - [Metric Directory](https://www.prereason.com/metrics): All 38 tracked metrics with descriptions (30 API metrics + 8 mining & energy briefing metrics) - [Briefing Directory](https://www.prereason.com/briefings): All 17 market briefings with tier info - [Evidence](https://www.prereason.com/evidence): Backtest results proving briefing effectiveness ## Use Cases - Portfolio rebalancing: Get market context before making allocation changes - Daily market briefings: Summarize current conditions across Bitcoin, macro, and cross-asset indicators - Automated research reports: Pull structured context into recurring analysis workflows - Automated analysis pipelines: Feed regime classification and context into recurring research and monitoring workflows - Financial AI training and evaluation: Use historical context windows as training or benchmark data for financial reasoning models - Risk assessment: Check cross-asset correlations, volatility levels, and liquidity conditions before taking positions ## Integrations - Claude Desktop: Add PreReason as an MCP server via npx (stdio bridge) - Claude Code: Add via .mcp.json or `claude mcp add` command (HTTP transport) - Cursor: Add remote MCP server pointing to https://api.prereason.com/api/mcp - Windsurf: Same MCP configuration as Cursor - ChatGPT: Use REST API with Bearer token auth in custom GPT actions - Any HTTP client: Standard REST API with JSON or markdown responses ## Search Keywords bitcoin data api, btc price api, crypto market data, cryptocurrency api, bitcoin analysis, market intelligence api, financial data api, macro indicators api, economic data api, fed balance sheet api, m2 money supply, treasury yields api, net liquidity data, bitcoin mining data, hash rate api, bitcoin difficulty, mining economics, hashprice, bitcoin correlation, cross-asset analysis, market regime api, risk classification, bitcoin momentum, technical analysis api, btc trend signals, bitcoin on-chain analytics, blockchain data api, bitcoin treasury holdings, corporate btc holdings, sec filings bitcoin, portfolio context api, trading signals api, risk assessment api, x402 financial api, pay per request market data, micropayment api, mcp financial tools, llm market context, bitcoin energy cost, miner stress index, dxy dollar index, fx liquidity, yield curve api, vix volatility api, market breadth, quantitative finance api, context api for ai agents, pre-reasoned market intelligence, financial context api, regime classification api, ai agent financial data, crypto portfolio context, bitcoin market briefing, llm backtest results, ai trading backtest, ai agent trading evidence, briefing backtest rct, llm trading performance, structured context vs raw data, ai financial agent benchmark, market context api backtest, bitcoin context api evidence, pre-analyzed data backtest