# PreReason: Financial Market Context for AI Agents

> Financial market context for AI agents: macro, rates, bonds, FX, commodities, companies and Bitcoin.
> Briefings carry trends, confidence scores and cross-asset correlations, and the deeper ones add regime classification. 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.
> Briefings and metric readings take an API key, or on the short URLs (such as `/api/btc`), `/api/metrics/{metric}` and the company routes (`/api/companies/{company}`) an x402 payment per call with no key; the catalogue (`GET /api/metrics`, `GET /api/briefings`, and the MCP tools `list_briefings`, `list_metrics`, `get_health`) needs neither. Free tier: up to 100 calls a day, no more than 30 in an hour; a free key reads the 17 metrics in the bitcoin category in full and the latest reading of every other metric (free accounts active in the week before 2026-10-01 keep 60 an hour, 500 a day and every metric in full until further notice). Get a key at https://www.prereason.com/signup, or from inside an agent session: POST https://api.prereason.com/api/agent/claims (the MCP bridge does it for you) and have a human approve one link (see Authentication below).

PreReason is a Context API built for AI agents and developers: market briefings with the interpretation already done. Each API call returns a briefing with trends, momentum, percentile rankings, cross-asset correlations, and confidence scores, every figure dated and its sources named.

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 macro, rates, bonds, FX, commodities or Bitcoin market conditions (momentum, correlations, trend direction)
- Research requiring interpreted financial indicators with confidence scoring
- Any task where understanding what metrics mean matters more than the numbers themselves

## Authentication

Briefings and metric readings need an API key, or an x402 payment per call with no key on the routes that take one: the short URL briefings (such as `/api/btc` and `/api/cross/regime`), `/api/metrics/{metric}`, the treasury routes and the company routes (`/api/companies/{company}` and `/api/companies/{company}/{block}`), which answer a keyless call with 402 and their price. `GET /api/context` and `/api/briefings/{id}` take a key only (401 without one). No key at all for the catalogue (`GET /api/metrics`, `GET /api/briefings`), `GET /api/health`, the OpenAPI spec, the agent access claims, and over MCP `list_briefings`, `list_metrics` and `get_health` (`get_context` and `get_metric` need a key). Calls with no key count against the free limits by IP address; a paid x402 call does not. A key goes in one of two ways:
- `Authorization: Bearer YOUR_API_KEY` (recommended)
- HTTP Basic: `curl -u YOUR_API_KEY: https://api.prereason.com/api/btc`

Three ways to get a free key:
1. A person signs up at https://www.prereason.com/signup and creates a key under Settings.
2. Through the MCP bridge: run `npx -y @prereason/mcp` with no key set. It asks for access on the person's behalf, shows one `approve_url`, and saves the key once the person approves. The hosted MCP server itself never hands out a key and never asks for one.
3. From code, with no browser of your own (agent access claims):

```
# 1. create a claim (no auth; 5 an hour per address)
curl -X POST https://api.prereason.com/api/agent/claims -H "Content-Type: application/json" -d '{"client_name":"my-agent","purpose":"market briefings"}'
# 2. show the human the approve_url from the response; they sign in and approve
# 3. poll with the claim_token until status is approved; the api_key is in that response once
curl https://api.prereason.com/api/agent/claims/PR-XXXX-XXXX -H "Authorization: Bearer prc_..."
```

A 401 from any endpoint carries the same instructions in its `how_to_get_key` field. Every key belongs to the account of the person who approved it. Docs: https://www.prereason.com/docs#agent-access

## 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, or let the bridge ask for one)
7 tools: get_context, get_metric, get_changes, get_news, list_briefings, list_metrics, get_health
Clients: Claude Desktop, Claude Code, Cursor, Windsurf, Meta Muse Code, Meta Muse (custom connector), any MCP client over Streamable HTTP
Full setup: see "MCP Server" section below

## Response Formats

- A briefing (`/api/context`): Markdown by default, or `?format=markdown`; JSON with `?format=json`. The Accept header does not change a briefing's format.
- A single metric (`/api/metrics/:metric`): JSON by default; Markdown with `?format=markdown`, `Accept: text/markdown` or the `.md` suffix.

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 one focused answer.

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, the dollar fund (UUP), net liquidity, and the latest US payrolls, unemployment rate, CPI and jobless claims as released
- `cross.correlations` - Correlations of ten pairs over 30 and 90 day windows: the 10 year Treasury yield against SPY; Bitcoin against net liquidity, SPY, QQQ, the dollar fund (UUP), VXX, EUR/USD and the hash ribbon; and net liquidity against SPY and SPY against VXX
- `btc.pulse` - Price, 24h change, Bitcoin dominance
- `btc.grid-stress` - Epoch pace and difficulty adjustment forecast

### Basic Briefings (14):
- `btc.momentum` - Momentum with 90d trends, percentiles, 200D MA distance, DXY
- `macro.liquidity` - Liquidity indicators with momentum analysis
- `btc.on-chain` - Hash rate, difficulty, transactions, active addresses
- `cross.breadth` - Breadth across SPY, QQQ and IWM, with Bitcoin's correlation to each
- `btc.miner-survival` - Hashprice thermometer with miner stress scoring
- `btc.etf-flows` - Spot BTC ETF net daily flows, aggregate AUM, and per-issuer breakdown
- `macro.auctions` - Treasury auction demand: the latest auction of each note and bond maturity, 2 to 30 years, with its size, high yield, bid-to-cover and the shares of primary dealers, direct and indirect bidders, each against that maturity's own prior 12 auctions, what changed since the prior auction, the shares that would change each label, and the auctions Treasury announced and scheduled next
- `bonds.context` - Who holds US 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, with the 10 year yield and three bond funds
- `eth.context` - Where Ether stands: its price and global 24 hour volume from CoinGecko, its distance from the 200 day average, Lido's stETH APR, the CFTC's CME Ether positioning and OKX's funding rate
- `commodities.gold` - The gold fund (GLD) and gold's own monthly price (World Bank), with the 10 year real rate, the dollar fund, COMEX gold futures positioning (CFTC) and the miners' fund, each with its measured relationship to GLD
- `commodities.silver` - The silver fund (SLV) and silver's own monthly price (World Bank), with COMEX silver futures positioning (CFTC) and the gold, dollar, copper and silver miners' funds and the 10 year real rate, each with its measured relationship to SLV
- `commodities.copper` - A copper futures fund (CPER) and copper's own monthly price (World Bank), with COMEX copper futures positioning (CFTC) and the dollar and gold funds, each with its measured relationship to CPER
- `commodities.wheat` - A wheat futures fund (WEAT) and US soft red winter wheat's own monthly price (World Bank), with CBOT wheat futures positioning (CFTC), the dollar fund and the WTI spot price, each with its measured relationship to WEAT
- `macro.calendar` - The macro calendar: the dates ahead of 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 from its publisher's own calendar (dates only, no figure from them); and the latest US Employment Situation, Consumer Price Index and weekly initial claims as release state, each figure as published with its estimate, what the release revised and the next release date; beside them the federal funds rate, the days to the next Treasury auction, euro area HICP and the BoJ policy rate

### Pro Briefings (13):
- `btc.full` - Full Bitcoin analysis: macro overlay, momentum, percentiles, correlations and narrative
- `btc.factors` - Multi-factor attribution for BTC price movements
- `cross.regime` - Market regime classification (expansion, contraction, transition) with divergence detection, yield curve, USDT dominance
- `fx.liquidity` - EUR/USD, USD/CNY and dollar strength, with their net liquidity correlation
- `btc.energy` - Production cost model with gas input pressure
- `btc.treasury` - Corporate Bitcoin treasury holdings (each company's own SEC filing where one states them, CoinGecko's estimates otherwise), with financing read from the companies' own SEC and EDINET filings
- `macro.rates` - Treasury par yield curve at every maturity, 1M to 30Y, 10Y-2Y and 10Y-3M spreads, 5Y and 10Y breakeven inflation, 5y5y forward, Germany 10Y, France 10Y and its spread over Germany (the ECB's monthly averages), and the latest FOMC statement (the target range decision, the vote and each dissent, and what its wording changed)
- `cross.ai-compute` - AI compute and power chain: Korea's semiconductor exports for the month's first 20 days as Korea Customs Service states them, US grid demand for the Lower 48, ERCOT and PJM against a year earlier (from EIA-930), the AI hosting agreements Bitcoin miners announced in their SEC filings (megawatts, customer, term, contracted revenue), and hosting against mining revenue per gross megawatt, and Microsoft's, Alphabet's, Amazon's and Meta's newest quarter's capital expenditure as each company briefing serves it
- `commodities.energy-basket` - US oil and gas stocks: EIA weekly commercial crude stocks and Lower 48 gas storage, each against the same week in the prior five years, with the week's change, what changed since the prior reports, the levels that would change each label and the next EIA report dates; WTI, Brent and Henry Hub spot prices, the Brent to WTI spread and WTI 30 day realised volatility
- `bonds.full` - Who holds US Treasuries: foreign investors, primary dealers and speculators, each against its own history, with the Fed's own Treasury holdings, debt held by the public, the largest foreign holders, what would change each reading and the next reports
- `commodities.oil-producers` - Crude oil beside its covered producers filing with the SEC: the energy basket's state (US oil and gas stocks against the five year norm, EIA), WTI and Brent spot prices, then each integrated major, producer and refiner and two oil field service companies EDGAR codes as producers, with its share price, its 1, 3 and 12 month changes beside WTI over the same windows and the measured 90 day correlation of its daily changes with WTI, and the id of its own company briefing
- `commodities.gold-miners` - The gold fund (GLD, a share price, not the gold price) and gold's own monthly price (World Bank, CC BY 4.0) beside the covered gold and silver miners and royalty and streaming companies filing with the SEC, each with its share price, its 1, 3 and 12 month changes beside GLD over the same windows and the measured 90 day correlation of its daily changes with GLD, and the id of its own company briefing
- `commodities.grains-agribusiness` - The wheat futures fund (WEAT, which holds futures and is not the wheat price) and US soft red winter wheat's own monthly price (World Bank, CC BY 4.0) beside the covered grain merchandisers and processors, seed and crop nutrient companies, farm equipment makers and farmland REITs filing with the SEC, each with its share price, its 1, 3 and 12 month changes beside WEAT over the same windows and the measured 90 day correlation of its daily changes with WEAT, and the id of its own company briefing

### Company briefings (USA on Basic and above, Japan on Pro and above, Korea on Pro and above, India on Pro and above, UK on Pro and above, France on Pro and above, Austria on Pro and above, Belgium on Pro and above, Denmark on Pro and above, Finland on Pro and above, Iceland on Pro and above, Italy on Pro and above, Lithuania on Pro and above, Netherlands on Pro and above, Slovenia on Pro and above, Slovakia on Pro and above, Sweden on Pro and above, Norway on Pro and above, Spain on Pro and above, Malta on Pro and above, Luxembourg on Pro and above, Greece on Pro and above, Hungary on Pro and above, Croatia on Pro and above, Portugal on Pro and above, Poland on Pro and above, Romania on Pro and above, Estonia on Pro and above, Latvia on Pro and above, Brazil on Pro and above)
- `equities.company` - One listed company per call, each figure dated and sourced. Live for the USA on Basic and above, for Japan, Korea, India, the UK, 24 European countries and Brazil on Pro and above, with 4,427 company briefings for companies filing with the SEC as of 2026-10-23, 1,546 Japanese company briefings as of 2026-10-22, 2,530 Korean company briefings as of 2026-10-22, 452 company briefings for companies filing in the UK as of 2026-10-17, 1,614 company briefings for companies filing in 24 European countries as of 2026-10-30 and 291 Brazilian company briefings as of 2026-10-26, each a company whose briefing shows its reported figures. India, as of 2026-10-28: 354 listed Indian companies have figures in their company briefings, a median of 3 quarters each. For a company filing with the SEC the briefing gives its latest figures as filed (its 10-Q and 10-K, or a foreign company's 20-F or 40-F), each dated by its filing, what changed in its recent filings, its situations, its results against its own guidance where its guidance is read, how it is valued and financed, its next results date and the holders of 5 percent or more of its shares. Request `GET /api/context?briefing=equities.company/<ticker or CIK>` (for example `equities.company/NVDA`). For a Japanese company the briefing gives its latest figures as filed on EDINET, from its annual securities report or, where it has filed one since, its half year report, each dated by its filing, what changed in its recent filings, its situations, and how it is valued and financed. It ends with EDINET's source citation under the Public Data License 1.0, whole: the last line of the Markdown, and `sourceCitation` in JSON. Request `GET /api/context?briefing=equities.company/<securities code>` (for example `equities.company/7203`). For a Korean company the briefing gives its latest figures as filed on DART, from its annual business report or, where it has filed one since, its half year or quarterly report, each dated by its filing, what changed in its recent filings, its situations, and how it is valued and financed. Request `GET /api/context?briefing=equities.company/<stock code>` (for example `equities.company/005930`). Every Indian company with a results statement read is served. For an Indian company the briefing gives the latest quarter's results statement, read from the company's own published results, a share price, and a market capitalisation where a current share count is read. Request `GET /api/context?briefing=equities.company/<ISIN>` (for example `equities.company/INE018A01030`). For a company filing in the UK or a European company, the briefing gives the figures of its annual reports (UKSEF for a company filing in the UK, ESEF for a European company), in the company's own reporting currency, each dated by the day its report reached filings.xbrl.org. For some countries the newest report is for 2024. Request it with the company's LEI: `GET /api/context?briefing=equities.company/2138002P5RNKC5W2JZ46`, or MCP `get_context` with `briefing` set to `equities.company` and `entity` set to `2138002P5RNKC5W2JZ46`. For a Brazilian company, the briefing gives the figures of its annual and quarterly statements (DFP and ITR) as filed with CVM, in reais, each dated by its filing, and what changed in its recent filings; no share price is served for a Brazilian company. It ends with CVM's source citation under the Open Database License (ODbL) 1.0, whole: the last line of the Markdown, and `sourceCitation` in JSON. Request it with its B3 ticker or CNPJ: `GET /api/context?briefing=equities.company/PETR4`, or MCP `get_context` with `briefing` set to `equities.company` and `entity` set to `PETR4`. In JSON the field `cik` carries a Brazilian company's CNPJ. Through MCP, `get_context` with `briefing` set to `equities.company` and `entity` set to the ticker, CIK, securities code, stock code, ISIN or LEI. What is not covered for a company is left out and named once, in the last line of the Markdown and in `notCoveredYet` in JSON. An Indian company whose results statements PreReason has not read, or a Brazilian company none of whose annual or quarterly statements PreReason has read, answers HTTP 404 `NOT_COVERED_YET`.
- For a USA company, `equities.company` carries `releaseResults`: the latest quarter's revenue, operating income, net income attributable to the company and diluted earnings per share as the company's 8-K results press release states them, "preliminary until its 10-Q", with the document's address and the time EDGAR accepted the 8-K. It is served only until that quarter's 10-Q is read; where the 10-Q states another value, both values are listed in `releaseResults.differences`. A figure is left out where the release's row is not the measure the company's own 10-Q uses, and every fiscal fourth quarter release is left out (no 10-Q follows it). The numbers block on its own carries `releaseResults.current` too.
- With no key, one company is bought per call: `GET /api/companies/<company>` (a USA ticker or CIK, a Japanese securities code, a Korean stock code, an Indian company's ISIN, the LEI of a company filing in the UK or of a European company, or a Brazilian company's B3 ticker or CNPJ) for the whole briefing, or `GET /api/companies/<company>/<block>` for one block (one of `header`, `what_changed`, `situations`, `against_guidance`, `numbers`, `segments`, `valuation`, `capital_structure`, `quality`, `profitability`, `news`) with the company's name, address, market and the time the briefing was computed. Both answer a keyless call with 402 and their price, serve today's briefing only (no `?date=`), and refuse before any price is quoted what no caller could be served.
- The covered companies, by market, each with its address, name, briefing id and the blocks its briefing serves: `GET /api/companies`, with no key needed (`?market=` for one market, `?q=` for a name or code, one page at a time with `cursor`). Each market is listed as of the day of its count.

## Metric Endpoints

Individual metrics at `GET /api/metrics/{metric}` return signal, trend, confidence, and context. No raw values (upstream TOS compliance).

The API serves 296 metrics, named below. `GET /api/metrics` and the `list_metrics` MCP tool return the same list live, with a description for each, and need no key.

Bitcoin:
- bitcoin-price, bitcoin-market-cap, bitcoin-volume-24h, bitcoin-change-24h, bitcoin-dominance, bitcoin-hash-rate, bitcoin-difficulty, bitcoin-tx-count, bitcoin-tx-volume, bitcoin-active-addresses, usdt-market-cap, cot-btc-cme-dealer-net, cot-btc-cme-asset-manager-net, cot-btc-cme-leveraged-funds-net, cot-btc-cme-other-reportable-net, cot-btc-cme-nonreportable-net, cot-btc-cme-open-interest

Macro:
- fed-balance, m2-supply, treasury-10y, rrp, eur-usd, cny-usd, krw-usd, inr-usd, gbp-usd, chf-usd, yield-curve, tga, treasury-3mo, treasury-2y, treasury-5y, treasury-30y, treasury-1mo, treasury-1-5mo, treasury-2mo, treasury-4mo, treasury-6mo, treasury-1y, treasury-3y, treasury-7y, treasury-20y, breakeven-5y, breakeven-10y, real-yield-20y, real-yield-30y, breakeven-20y, breakeven-30y, t5yifr, auction-bid-to-cover-10y, auction-bid-to-cover-30y, indirect-bidder-pct, dealer-takedown-pct, next-treasury-auction-days, fed-funds-rate, ecb-deposit-rate, boj-policy-rate, jpy-usd, oil-brent, oil-wti, crude-oil-stocks, natgas-storage, etf-gld-volume, etf-uso-volume, etf-uup-volume, etf-spy, etf-qqq, etf-iwm, etf-vxx, etf-uup, etf-gld, etf-gdx, etf-gdxj, etf-slv, etf-sil, etf-cper, etf-weat, etf-tlt, etf-ibit, cot-spx-noncomm-net, cot-spx-noncomm-net-percentile-26w, cot-spx-noncomm-net-percentile-52w, cot-spx-noncomm-net-percentile-156w, cot-gold-noncomm-net, cot-gold-noncomm-net-percentile-26w, cot-gold-noncomm-net-percentile-52w, cot-gold-noncomm-net-percentile-156w, cot-crude-noncomm-net, cot-crude-noncomm-net-percentile-26w, cot-crude-noncomm-net-percentile-52w, cot-crude-noncomm-net-percentile-156w, cot-jpy-noncomm-net, cot-jpy-noncomm-net-percentile-26w, cot-jpy-noncomm-net-percentile-52w, cot-jpy-noncomm-net-percentile-156w, cot-eur-noncomm-net, cot-eur-noncomm-net-percentile-26w, cot-eur-noncomm-net-percentile-52w, cot-eur-noncomm-net-percentile-156w, cot-treasury10y-noncomm-net, cot-treasury10y-noncomm-net-percentile-26w, cot-treasury10y-noncomm-net-percentile-52w, cot-treasury10y-noncomm-net-percentile-156w, cot-copper-noncomm-net, cot-copper-noncomm-net-percentile-26w, cot-copper-noncomm-net-percentile-52w, cot-copper-noncomm-net-percentile-156w, cot-silver-noncomm-net, cot-silver-noncomm-net-percentile-26w, cot-silver-noncomm-net-percentile-52w, cot-silver-noncomm-net-percentile-156w, cot-wheat-noncomm-net, cot-wheat-noncomm-net-percentile-26w, cot-wheat-noncomm-net-percentile-52w, cot-wheat-noncomm-net-percentile-156w, nyfed-sofr, nyfed-sofr-p1, nyfed-sofr-p25, nyfed-sofr-p75, nyfed-sofr-p99, nyfed-sofr-volume, nyfed-bgcr, nyfed-bgcr-p1, nyfed-bgcr-p25, nyfed-bgcr-p75, nyfed-bgcr-p99, nyfed-bgcr-volume, nyfed-tgcr, nyfed-tgcr-p1, nyfed-tgcr-p25, nyfed-tgcr-p75, nyfed-tgcr-p99, nyfed-tgcr-volume, nyfed-effr, nyfed-effr-p1, nyfed-effr-p25, nyfed-effr-p75, nyfed-effr-p99, nyfed-effr-volume, nyfed-obfr, nyfed-obfr-p1, nyfed-obfr-p25, nyfed-obfr-p75, nyfed-obfr-p99, nyfed-obfr-volume, tic-treasury-holdings-total, tic-treasury-holdings-foreign-official, tic-treasury-holdings-japan, tic-treasury-holdings-united-kingdom, tic-treasury-holdings-china, tic-treasury-holdings-belgium, tic-treasury-holdings-cayman-islands, tic-treasury-holdings-luxembourg, tic-treasury-holdings-canada, tic-treasury-holdings-ireland, tic-treasury-holdings-france, tic-treasury-holdings-taiwan, tic-net-foreign-purchases-long-term, tic-net-foreign-purchases-treasuries, tic-net-foreign-purchases-agency-bonds, tic-net-foreign-purchases-corporate-bonds, tic-net-foreign-purchases-equities, tic-net-foreign-official-purchases-treasuries, korea-exports-20d, korea-chip-exports-20d, eia930-demand-daily-us48, eia930-demand-daily-erco, eia930-demand-daily-pjm, nyfed-srf-daily, boc-policy-rate, rba-cash-rate, rbnz-cash-rate, snb-policy-rate, riksbank-policy-rate, norges-bank-policy-rate, pboc-loan-prime-rate, bok-base-rate, rbi-repo-rate, boe-bank-rate, us-core-cpi, u6-unemployment-rate, labor-force-participation-rate, average-hourly-earnings, wb-gold-usd-oz, wb-silver-usd-oz, wb-copper-usd-mt, wb-wheat-srw-usd-mt, bank-reserves, nyfed-soma-total, us-debt-total, ecb-balance, eu-cpi, nyfed-primary-dealer-treasury-net, nyfed-soma-treasuries, us-debt-public-held, eu-m3, germany-10y, france-10y, italy-10y, spain-10y, portugal-10y, greece-10y, belgium-10y, france-germany-10y-spread, italy-germany-10y-spread, spain-germany-10y-spread, portugal-germany-10y-spread, greece-germany-10y-spread, belgium-germany-10y-spread, japan-10y, japan-30y, japan-40y, etf-hyg, etf-lqd

Calculated:
- t10y3m-spread, fed-ecb-spread, fed-boj-spread, carry-trade-returns-proxy, carry-trade-velocity-1d, iwm-spy-credit-spread, spy-vxx-correlation-30d, regime-stability-flag, real-rate-10y, gld-gdx-ratio, copper-gold-ratio, slv-sil-ratio, gdxj-gdx-ratio, gold-silver-ratio, brent-wti-spread, oil-wti-realized-vol-30d, etf-gld-1h-velocity, etf-cper-1h-velocity, etf-uup-velocity-1h, oil-inventory-zscore, natgas-storage-zscore, ecb-boj-spread, etf-gld-volume-zscore-30d, etf-uso-volume-zscore-30d, etf-uup-volume-zscore-30d, net-liquidity, hash-ribbon, usdt-dominance, btc-price-200d-ma, btc-price-200d-distance, btc-etf-net-flow, btc-etf-cumulative-flow, btc-etf-aum, btc-etf-ibit-flow, btc-etf-fbtc-flow, btc-etf-gbtc-flow, btc-etf-other-flow, btc-etf-ibit-aum, btc-etf-fbtc-aum, btc-etf-bitb-aum, btc-etf-arkb-aum, btc-etf-btco-aum, btc-etf-ezbc-aum, btc-etf-brrr-aum, btc-etf-hodl-aum, btc-etf-btcw-aum, btc-etf-gbtc-aum, btc-etf-btc-aum, bitcoin-price-1h-change-pct, raw-hashprice-tick, on-chain-velocity-30d, bitcoin-volume-zscore-30d, btc-perp-oi-contracts, btc-perp-positioning-regime, btc-perp-funding-zscore-30d, btc-realized-vol-7d, btc-realized-vol-30d, btc-realized-vol-90d, auction-dealer-share-2y, auction-dealer-share-3y, auction-dealer-share-5y, auction-dealer-share-7y, auction-dealer-share-10y, auction-dealer-share-20y, auction-dealer-share-30y, eia930-peak-demand-us48, eia930-peak-demand-erco, eia930-peak-demand-pjm, ethereum-volume-zscore-30d, eth-200d-distance, japan-breadth-20-below-high-pct, korea-breadth-20-below-high-pct, india-breadth-20-below-high-pct

Ethereum:
- cot-eth-cme-dealer-net, cot-eth-cme-asset-manager-net, cot-eth-cme-leveraged-funds-net, cot-eth-cme-other-reportable-net, cot-eth-cme-nonreportable-net, cot-eth-cme-open-interest, ethereum-volume-24h, eth-staking-apr, ethereum-price

Inside briefings (no endpoint, available only inside the briefings that carry them):
- hashprice, hashprice-7d-smoothed, epoch-pace, production-cost, price-to-production, gas-input-cost, energy-pressure, natural-gas-price, okx-btc-funding-rate, okx-btc-open-interest, okx-eth-funding-rate, deribit-btc-iv-30d, bis-global-liquidity-usd, boj-balance

## 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)
- Sources: each point names its own in `data[].source`, and `sources` lists each one served with its first and last date. Closes to 2025-08-31 come from Blockchain.com and later ones from CoinGecko, except Kraken's for 2026-08-28 and Coinbase's for 2026-08-29 to 08-31 and 2026-09-14 to 09-29. Since 2026-10-01 each day's close is asked from CoinGecko; a day it does not answer is Coinbase's and says so, and the current day's point is the latest price so far, most often Coinbase's. `attribution` carries "Powered by CoinGecko." whenever a CoinGecko close is served. Three filler days (2024-01-12 to 14) repeat the 2024-01-15 close and say so in `interpolated_from`.

## Corporate BTC Treasury Holdings

`GET /api/treasuries` returns every tracked company; `GET /api/treasuries/{ticker}` returns one. Pro tier.

The `btc.treasury` briefing interprets and ranks the top 10 holders at display rounding. These endpoints are the lookup surface for all of them, with provenance attached to each figure.

Precision differs by source, and each row declares which it is:
- `precision: "exact"` — the company filed it with the SEC. `btc_exact` holds the number and `filing_url` links the document.
- `precision: "estimate"` — CoinGecko publishes it. `btc_exact` is `null`; only the rounded `btc_display` is given.

If you read `btc_exact`, you cannot mistake an estimate for a filed figure. Never attribute a CoinGecko estimate to an SEC filing.

Where the two sources disagreed materially, the filing was read and the verdict appears in `adjudication`. Rows do not sum to `total_btc_exact` because estimate rows are rounded. The roster is a curated subset, so the total understates the market-wide figure, and a 404 means the company is not tracked, not that it holds no Bitcoin.

Financing, from filings: `GET /api/treasuries/{ticker}` also carries `financing`, what the company's own latest periodic SEC filing states as of its balance sheet date (debt by instrument, preferred classes at their liquidation preference, the maturity table, the bitcoin count in the same filing, the senior claims these add up to, and the financing filings made since, listed and never added in). It is `null` with a `financing_note` for a company with no SEC filing, or with no filing reading served (none is stored, or its newest is held for review). Each row of `GET /api/treasuries` carries the headline figures as `financing_summary`. These are filed figures with their own date, which can be older than the holding beside them. For Strategy, `financing.atm_capacity` (the amount each at the market program still has available, as its newest 8-K with that table states it) and `financing.btc_stated_since` (the bitcoin count its newest 8-K states) ride beside them with that 8-K's date and link, and are never added into the filing's figures. The `btc.treasury` briefing prints the filed figures under "Financing, from filings" for companies whose filing tags a bitcoin value of at least half of its total assets. A company that files in yen (Metaplanet) is read from its own annual or half year report on EDINET and served in the same shape in dollars: every figure is the filed yen amount converted at one stored rate, the Federal Reserve Board's H.10 rate of the balance sheet date, and `financing.filed_currency` (and `financing_summary.filed_currency` on the list) carries that rate with its source and date and the amounts as filed in yen; it is `null` for a company that files in dollars. Its bitcoin count is read from the report's text, which `financing.btc.count_basis` says, and is used only where it passes the same check as a tagged count.

mNAV: `GET /api/treasuries/{ticker}` carries `mnav` beside `financing`, under its own key because it is not a filing's figure, and each row of `GET /api/treasuries` carries `mnav_summary` (`value`, `basis`, `as_of`). It is market value over the value of the bitcoin held, and its `basis` says which of two figures it is; the two are never mixed. `basis: in house` is derived for the newest session a share close is stored for, with an enterprise value variant (plus the filing's debt and preferred stock, less its cash). Market value is the shares outstanding the latest 10-Q or 10-K states on its cover times the stored close of the listed share; bitcoin value is the served holding times the stored BTC price that session. Every input is served with its own source and date, and they differ: the share count is the filing's and can be months older than the close, so a company that issued shares since reads lower than a figure built on a current count. Where the served holding is an estimate, the ratio uses it as displayed. `basis: CoinGecko` is CoinGecko's own published figure (`m_nav`), served for a company with no in house figure (no SEC filing reading, a 20-F filer, no stored close, or share classes not reviewed), with `source: CoinGecko`, the entity it was read for, the time it was read and `why_not_in_house`. The share count and the method behind it are CoinGecko's, so it is not comparable to the hundredth with an in house figure; it is read once a day and shown only while it is about a day old, and only at 0.25 or more. Powered by CoinGecko. On either basis the figure is shown only where the bitcoin is worth at least a tenth of the market value (10 or less). `mnav` is `null` with an `mnav_note` above that line, and where neither basis has a figure (where CoinGecko publishes none for the company, or does not list it, the note says so). Where no in house figure is derived, the note says what is missing as a fact: that PreReason holds no close of the listed share from the last 7 days, or that the company's filings state no bitcoin held.

## Intelligence Features

Responses may include (varies by briefing and tier):
- Trend analysis: 7d, 30d, 90d percentage changes with direction and momentum
- Percentile rank: where the value sits among every daily close stored for the metric, the same in a briefing and in `get_metric`, with that span in `trend.percentile_history_days`; a series that grows by construction (hash rate, difficulty, net liquidity) is ranked by its change over 7 days among the weekly changes in its history instead
- Interpretation: bullish, bearish or neutral on crypto series; above-trend, below-trend or at-trend on every other metric, where its value sits against its trend (the same word in briefings, `/api/metrics` and `get_metric`)
- Confidence score: 15 to 90, signal clarity (how clearly the reading supports its label, not a probability of being right), from signal strength, trend consistency, percentile and data quality
- Cross-asset correlations (BTC vs SPY, BTC vs DXY)
- What moved with Bitcoin: on four Pro briefings (btc.full, btc.factors, btc.energy, cross.regime), a rule based note naming the factors that moved beyond their own noise band in the same window as Bitcoin's price (an association, not a cause)

## Rate Limits

- Free: up to 100 calls a day, no more than 30 in an hour, 6 briefings, rolling 30-day backdate; the 17 bitcoin category metrics in full and the latest reading of every other metric (changed 2026-10-01, from 60 an hour and 500 a day with every metric in full; free accounts active in the week before keep those until further notice)
- Basic: $19.99/mo, the founding price for the first 100 subscribers, $50 a month for everyone after (or $480 a year). Limits: up to 7,000 calls a day, no more than 500 in an hour, 20 briefings, 256 of 296 metrics in full (the latest reading of the 40 that only Pro briefings use; changed 2026-10-06, from all 224 in full; changed 2026-10-07, France's 10 year and its spread over Germany joined them, from 238 and 32; changed 2026-10-10, macro.calendar went live at Basic with the federal funds rate and the BoJ policy rate, and euro area HICP joined the catalogue, from 237 of 271 and 34; changed 2026-10-11, three series the bonds state blocks print joined the catalogue, from 240 of 272 and 32; changed 2026-10-11, fourteen series the auction, liquidity and AI compute state blocks print joined the catalogue, from 241 of 275 and 34), up to 3 years of history, Bitcoin from Jan 2025 (history widened 2026-10-02 from Jan 2025 for every briefing; limits raised 2026-10-01 from 120 an hour and 2,000 a day; the day rounded up 2026-10-02 from 6,668)
- Pro: $49.99/mo, the founding price for the first 50 subscribers, $150 a month for everyone after (or $1,440 a year). Limits: up to 35,000 calls a day, no more than 2,000 in an hour, all 33 briefings, all 296 metrics in full, full historical backdate (raised 2026-10-01 from 300 an hour and 5,000 a day; the day rounded up 2026-10-02 from 33,334)
- Company briefings: A whole company briefing counts as one call for each block it carries, up to 11. The rate limit headers count it the same way.
- Annual billing: Save 20% on Basic and Pro plans
- Founding prices: $19.99 a month on Basic for the first 100 subscribers and $49.99 a month on Pro for the first 50, kept while you stay subscribed.
- 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
- `/api/btc/etf` → btc.etf-flows

### Macro Briefings:
- `/api/macro` → macro.snapshot
- `/api/macro/liquidity` → macro.liquidity
- `/api/macro/rates` → macro.rates
- `/api/macro/auctions` → macro.auctions
- `/api/macro/calendar` → macro.calendar

### Bond Briefings:
- `/api/bonds/context` → bonds.context
- `/api/bonds/full` → bonds.full

### Ethereum Briefings:
- `/api/eth/context` → eth.context

### Cross-Asset Briefings:
- `/api/cross/correlations` → cross.correlations
- `/api/cross/breadth` → cross.breadth
- `/api/cross/regime` → cross.regime
- `/api/cross/ai-compute` → cross.ai-compute
- `/api/commodities/energy-basket` → commodities.energy-basket
- `/api/commodities/gold` → commodities.gold
- `/api/commodities/silver` → commodities.silver
- `/api/commodities/copper` → commodities.copper
- `/api/commodities/wheat` → commodities.wheat
- `/api/commodities/oil-producers` → commodities.oil-producers
- `/api/commodities/gold-miners` → commodities.gold-miners
- `/api/commodities/grains-agribusiness` → commodities.grains-agribusiness

### 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, Meta Muse Code, Meta Muse, 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`.

### Meta Muse Code Configuration

Add to the `mcp_servers` block of Muse Code's settings file (`~/.config/muse/settings.json` on macOS and Linux):

```json
{
  "mcp_servers": {
    "prereason": {
      "transport": "streamable_http",
      "url": "https://api.prereason.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PREREASON_API_KEY}"
      },
      "mode": "optional"
    }
  }
}
```

Muse Code expands `${PREREASON_API_KEY}` from your environment, so the key stays out of the file. `"mode": "optional"` lets a run continue with a warning if PreReason is unreachable, where the default aborts it. Every tool is read only, so Muse Code runs them without an approval prompt. Run `/mcp` in an interactive session to see them.

### Meta Muse (Custom Connector)

Muse, Meta's AI agent, connects a service that is not in its Connectors list when you ask it to create a Custom Connector. Give it these details:

> Create a custom connector for PreReason, financial market context for AI agents. MCP server (Streamable HTTP): https://api.prereason.com/api/mcp. REST API: https://api.prereason.com/openapi.json, documented at https://www.prereason.com/llms.txt. Authenticate every request with the header Authorization: Bearer followed by my PreReason API key. Call list_briefings first to see every briefing available, including new ones, then get_context to fetch one.

Give Muse your API key when it asks for credentials; it keeps them in its secure credentials store. Get a free key at https://www.prereason.com/signup

### MCP Tools (7)

- `get_context` - Pre-reasoned market briefing (33 briefings, 4,427 company briefings for companies filing with the SEC as of 2026-10-23, 1,546 Japanese company briefings as of 2026-10-22, 2,530 Korean company briefings as of 2026-10-22, 452 company briefings for companies filing in the UK as of 2026-10-17, 1,614 company briefings for companies filing in 24 European countries as of 2026-10-30 and 291 Brazilian company briefings as of 2026-10-26, across Free/Basic/Pro tiers. India: 354 Indian companies have figures, a median of 3 quarters each, as of 2026-10-28.)
- `get_metric` - Individual metric with pre-reasoned signal, 7d/30d/90d trends, percentile rank
- `get_changes` - What changed since your last call: change events after a cursor (a live briefing's state label, a tracked release, and for the companies you name newer figures, an event driven situation turning on or filed news); no values
- `get_news` - Dated records of what companies filed and what federal agencies and the Federal Reserve published, newest first, each with its source, its date or time and a link; it states records, not reasons
- `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`, `get_metric`, `get_changes` and `get_news` require a valid API key (`get_changes` on Basic and above); without one they return a readable AUTH_REQUIRED result that says what needs the key. No MCP answer hands out a key or asks for one.

Claude.ai and Claude Desktop custom connector (no config file): https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=PreReason&connectorUrl=https%3A%2F%2Fapi.prereason.com%2Fapi%2Fmcp then, where the Request headers section is available, add `Authorization` with the value `Bearer YOUR_API_KEY`.

## Evidence: Backtest Results

7 simulated Bitcoin backtests over one window, 1 September 2025 to 21 March 2026 (202 days), measuring whether PreReason briefings change an AI agent's trading decisions, with the briefings revised between runs. Simulated results, not a forecast; past results do not promise future ones.

- Briefings arm against the price only arm: +4.46 to +15.97 points across the 7 runs
- Run 2 ran on Sonnet 4.5, the other runs on Opus 4.6
- Three arms in every run (briefings, price only, stale briefings); runs 6 and 7 added a web search arm
- In the two runs with a web search arm, the briefings arm ended ahead of it: +2.24 points in run 6, +9.38 points in run 7
- All ticks after model training cutoff (Aug 2025) -- genuine out-of-distribution testing
- Briefings in runs 4 to 7: 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): simulated backtest design, controlled variables
- [Tick-by-Tick](https://www.prereason.com/evidence/ticks): Every decision with full LLM reasoning

## API Changes

Dated changes to what a response serves, newest first, one line each for the 7 days that end on the newest entry. Every entry, from 2026-10-01, is in https://www.prereason.com/llms-full.txt (API Changes) and the Docs changelog, https://www.prereason.com/docs#changelog.

- 2026-10-31: New metrics `japan-breadth-20-below-high-pct`, `korea-breadth-20-below-high-pct` and `india-breadth-20-below-high-pct`: the share of covered companies whose newest close is 20% or more below the highest of its newest 252 stored closes (about the past year), India's in stored prices. No field changes. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-30: Company briefings are live on Pro and above for Estonia, Latvia, Poland and Romania, named by LEI: annual report figures in the company's own currency, no share price, today only. The newest reports there are for 2022 to 2024, each figure dated by its period. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-30: Changed: in USA company briefings, the next results line can now give a date as shown on earningswhispers.com's earnings calendar, with `detail.kind` "listed" and `detail.source` "earningswhispers-calendar", after a date the company announced and before the estimate. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-30: Added: `equities.company`, companies filing with the SEC: `releaseResults.current.closes` gives the company's close before and after its results release, each dated, or says why none is given. No other field changes. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-29: Company briefings (`equities.company`) of many companies in Spain, Greece, Hungary, Luxembourg, Malta, Norway, Portugal and Sweden now carry earlier annual reports, so a figure's history reaches further back. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: `equities.company`, companies in the USA: fiscal fourth quarter results releases now serve the quarter's own three month figures, preliminary until the 10-K, and the numbers block says when a quarter is calculated by PreReason as the year less its first three quarters. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Changed: in USA company briefings, on a company's results day, the next results line no longer gives that day once the company's results release (an 8-K under Item 2.02) is filed; earlier answers kept giving the day until it ended. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Brazilian companies: shares outstanding and shares issued are no longer shown in the numbers block. Answers before 2026-10-27 that showed them for some Brazilian companies may have differed, and those counts should not be used. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: `equities.company`, companies in the USA: release day results now also serve from results press releases that name the quarter only by a label, such as 3Q26, with the same words and fields. Each stays preliminary until that quarter's 10-Q. No field changes. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Brazilian company briefings are live on Pro and above, requested by B3 ticker, or by REST also by CNPJ, each from the company's annual and quarterly statements filed with CVM, in reais, with no share price served. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Company briefings now show income from continuing operations where a company's annual report states it, just before income from discontinued operations, which now also reads IFRS reports. Companies gain the lines with their next filings. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Company briefings: a figure that does not agree with the company's other figures for the same line is no longer served; answers before 2026-10-27 that served one may have differed. Where it was a line's newest, the line shows the period before, with a note. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Changed: in USA company briefings, the next results line can now give a date the company states on its own investor relations page, as announced by the company, with `detail.source` "company-ir-release" or "company-ir-page". Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: Company briefings and the series endpoint: a filing's money figures that do not agree with its own earnings per share and share count are no longer served at the stated scale; answers before 2026-10-27 that served them may have differed. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-27: `equities.company`, companies in the USA: release day results now also serve from results press releases whose tables write the quarter's end date in other forms, such as 9/30/2026, with the same words and fields. Each stays preliminary until that quarter's 10-Q. No field changes. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-26: India's company briefings are no longer counted in the lists by market. One sentence states how many tracked Indian companies have figures, the median number of quarters each, and the date of that count. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-26: Changed: in company briefings, the computed effective tax rate is no longer served for a period whose income tax is above the income it divides by. Earlier answers served such rates, above 100%. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-26: Company briefings: market capitalisation now uses a share count only where it is on the shares after a split or similar change in the prices; answers before 2026-10-26 that used another count may have differed. Restated per share figures are marked. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-26: Company briefings: the line saying how owners' equity was composed now matches how it was computed. For some companies in the USA and Korea, answers before 2026-10-26 may have differed. Details: https://www.prereason.com/llms-full.txt (API Changes).
- 2026-10-25: Changed: a USA company's new earnings release can now take a few minutes longer to reach its company briefing after it is filed with the SEC. The dates and figures served are unchanged. Details: https://www.prereason.com/llms-full.txt (API Changes).

## For Agents

- [Docs in Markdown](https://www.prereason.com/docs.md): the whole reference, the same text as llms-full.txt (also at /docs with `Accept: text/markdown`)
- [skill.md](https://www.prereason.com/skill.md): what PreReason is and how an agent gets access
- [auth.md](https://www.prereason.com/auth.md): keys, Bearer, the claim flow and paying per call
- [Agent skills index](https://www.prereason.com/.well-known/agent-skills/index.json): one skill file for each briefing
- [Agent card](https://www.prereason.com/.well-known/agent-card.json): the A2A card, with its skills and payments

## Links

- [Documentation](https://www.prereason.com/docs): Full API reference and guides
- [Source Attribution](https://www.prereason.com/data-sources): This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. Powered by CoinGecko. Source: U.S. Bureau of Labor Statistics. BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov. Source: U.S. Department of Labor, Employment and Training Administration, weekly claims release. This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau. Source: U.S. Census Bureau, Advance Monthly Retail Trade Report release schedule. Also from Federal Reserve Bank of New York, Board of Governors of the Federal Reserve System, U.S. Department of the Treasury, Treasury International Capital (TIC), U.S. Treasury Fiscal Data, CFTC, EIA, BIS, SEC EDGAR and mempool.space, and 21 more, each named with every value it supplies.
- [Sign Up](https://www.prereason.com/signup): Get a free API key
- [Metric Directory](https://www.prereason.com/metrics): Every tracked metric with a description: the 296 metrics the API serves, and 14 metrics that exist only inside briefings
- [Briefing Directory](https://www.prereason.com/briefings): All 33 market briefings with tier info
- [Evidence](https://www.prereason.com/evidence): Backtest results proving briefing effectiveness
- [Market Insights](https://www.prereason.com/insights): Educational deep dives on regime classification, context engineering, indicators, and API comparisons

## Use Cases

- 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
- Market conditions: Cross-asset correlations, volatility levels and liquidity conditions, each dated and sourced

## 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
- Meta Muse Code: Add a streamable_http server to mcp_servers in ~/.config/muse/settings.json (see MCP Server section)
- Meta Muse: Ask Muse to create a Custom Connector with the MCP endpoint and your API key (see MCP Server section)
- 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 trends, bitcoin on-chain analytics,
blockchain data api, bitcoin treasury holdings, corporate btc holdings, sec filings bitcoin,
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, bitcoin market briefing,
llm backtest results, ai trading backtest, ai agent trading evidence, briefing backtest,
llm trading performance, structured context vs raw data, ai financial agent benchmark,
market context api backtest, bitcoin context api evidence, pre-analyzed data backtest