# Mercury402

> Deterministic financial data for AI agents: FRED macro series, US Treasury yields,
> forex cross-rates, yield-curve spreads, breakeven inflation and macro composites.
> Pay per call in USDC on Base via x402 (HTTP 402) — no API keys, no subscription.

Base URL: https://api.mercury402.com
Paid endpoints: 78 (prices in USD, settled in USDC on Base)

## Discovery
- x402 payment descriptors: https://api.mercury402.com/.well-known/x402
- OpenAPI 3.1 spec: https://api.mercury402.com/openapi.json
- JSON manifest: https://api.mercury402.com/meta.json
- Quickstart: https://api.mercury402.com/docs/quickstart
- MCP server (stdio): npx -y mercury402-mcp

## How to call a paid endpoint
1. Call the endpoint without payment: HTTP 402 with a Payment-Required header carrying the price and payTo address.
2. Sign an EIP-3009 transferWithAuthorization for the quoted amount and retry the same request with a PAYMENT-SIGNATURE header.
3. Success returns the data plus signed provenance. Requests that fail upstream are not charged.

## Endpoints

### ai

- POST /v1/ai/ask — $0.15 — Ask the Data: natural-language question answered ONLY from chosen Mercury402 FRED series (grounded, cited)
- GET /v1/ai/briefing — $0.10 — AI Macro Briefing: analyst narrative written strictly from live FRED data (growth, prices, labor, Fed funds)

### breakeven-inflation

- GET /v1/breakeven/10y — $0.05 — 10-year breakeven inflation rate (TIPS)
- GET /v1/breakeven/2y — $0.05 — 2-year breakeven inflation rate (TIPS)
- GET /v1/breakeven/5y — $0.05 — 5-year breakeven inflation rate (TIPS)
- GET /v1/breakeven/5y5y — $0.05 — 5-year, 5-year forward inflation expectation rate

### composite

- GET /v1/composite/economic-dashboard — $0.50 — Economic overview: GDP, CPI, and Unemployment in one call
- GET /v1/composite/inflation-tracker — $0.40 — Inflation metrics: CPI, PCE, and Core CPI
- GET /v1/composite/labor-market — $0.40 — Labor market health: Unemployment, Jobless Claims, Nonfarm Payrolls

### forex

- GET /v1/forex/eur-usd — $0.05 — Euro area / US dollar exchange rate (DEXUSEU)
- GET /v1/forex/gbp-usd — $0.05 — US / UK pound exchange rate (DEXUSUK)
- GET /v1/forex/usd-cny — $0.05 — China / US dollar exchange rate (DEXCHUS)
- GET /v1/forex/usd-jpy — $0.05 — Japan / US dollar exchange rate (DEXJPUS)

### fred

- GET /v1/fred/{series_id} — $0.05 — Federal Reserve Economic Data (FRED) series (Price doubles (2x) for a multi-observation response: when both observation_start and observation_end are supplied, or when limit > 1.)
- GET /v1/fred/a-rated-spread — $0.05 — ICE BofA Single-A US Corporate Index OAS
- GET /v1/fred/average-hourly-earnings — $0.05 — Average hourly earnings of all employees, total private
- GET /v1/fred/bbb-corporate-yield — $0.05 — ICE BofA BBB US Corporate Index Option-Adjusted Yield
- GET /v1/fred/building-permits — $0.05 — New privately-owned housing units authorized (thousands)
- GET /v1/fred/case-shiller — $0.05 — S&P/Case-Shiller US National Home Price Index
- GET /v1/fred/conference-board-ci — $0.05 — Conference Board consumer confidence index (OECD)
- GET /v1/fred/consumer-confidence — $0.05 — University of Michigan consumer sentiment index
- GET /v1/fred/continuing-claims — $0.05 — Continued claims, weekly
- GET /v1/fred/corporate-profits — $0.05 — Corporate profits after tax
- GET /v1/fred/cpi — $0.05 — Consumer Price Index for All Urban Consumers (CPIAUCSL)
- GET /v1/fred/cpi-core — $0.05 — Core CPI (excl. food & energy, CPILFESL)
- GET /v1/fred/current-account — $0.05 — Current account balance, billions of USD
- GET /v1/fred/existing-home-sales — $0.05 — Existing home sales, millions (SAAR)
- GET /v1/fred/fed-funds-rate — $0.05 — Effective federal funds rate
- GET /v1/fred/fed-funds-target-upper — $0.05 — Federal funds target rate, upper bound
- GET /v1/fred/federal-debt — $0.05 — Federal debt as percent of GDP
- GET /v1/fred/federal-deficit — $0.05 — Federal surplus or deficit, billions
- GET /v1/fred/gdi — $0.05 — Real GDI
- GET /v1/fred/gdp — $0.05 — Real GDP, billions of chained 2017 dollars
- GET /v1/fred/gdp-deflator — $0.05 — Gross domestic product: implicit price deflator
- GET /v1/fred/gdp-growth — $0.05 — Real GDP percent change, annualized
- GET /v1/fred/high-yield-spread — $0.05 — ICE BofA US High Yield Index Option-Adjusted Spread
- GET /v1/fred/homeownership-rate — $0.05 — Homeownership rate for the US
- GET /v1/fred/housing-starts — $0.05 — New privately-owned housing units started (thousands)
- GET /v1/fred/industrial-production — $0.05 — Industrial production: total index
- GET /v1/fred/inflation-expectations — $0.05 — University of Michigan 1-year inflation expectations
- GET /v1/fred/initial-claims — $0.05 — Initial jobless claims, weekly
- GET /v1/fred/jolts-openings — $0.05 — Job Openings and Labor Turnover Survey
- GET /v1/fred/labor-force-participation — $0.05 — Labor force participation rate
- GET /v1/fred/leading-indicators — $0.05 — Conference Board Leading Economic Index for the US
- GET /v1/fred/m1-money-stock — $0.05 — M1 money stock, seasonally adjusted
- GET /v1/fred/m2-money-stock — $0.05 — M2 money stock, seasonally adjusted
- GET /v1/fred/mortgage-30y — $0.05 — 30-year fixed-rate mortgage average
- GET /v1/fred/nonfarm-payrolls — $0.05 — Total nonfarm payrolls (thousands)
- GET /v1/fred/pce — $0.05 — Personal Consumption Expenditures (PCE)
- GET /v1/fred/pce-core — $0.05 — Core PCE Price Index (excl. food & energy)
- GET /v1/fred/pce-deflator — $0.05 — PCE deflator, percent change from year ago
- GET /v1/fred/personal-income — $0.05 — Personal income, billions of USD
- GET /v1/fred/personal-saving-rate — $0.05 — Personal saving rate (percent)
- GET /v1/fred/ppi — $0.05 — Producer Price Index for All Commodities
- GET /v1/fred/quits-rate — $0.05 — Quits rate (JOLTS)
- GET /v1/fred/retail-sales — $0.05 — Advance retail sales: retail and food services (millions)
- GET /v1/fred/total-vehicle-sales — $0.05 — Total vehicle sales, millions (SAAR)
- GET /v1/fred/trade-balance — $0.05 — Trade balance: goods and services, millions of USD
- GET /v1/fred/treasury-10y — $0.05 — 10-year Treasury constant maturity rate
- GET /v1/fred/treasury-2y — $0.05 — 2-year Treasury constant maturity rate
- GET /v1/fred/treasury-30y — $0.05 — 30-year Treasury constant maturity rate
- GET /v1/fred/treasury-3m — $0.05 — 3-month Treasury constant maturity rate
- GET /v1/fred/treasury-5y — $0.05 — 5-year Treasury constant maturity rate
- GET /v1/fred/u6-unemployment — $0.05 — Total unemployed + marginally attached + part-time for economic reasons
- GET /v1/fred/unemployment-rate — $0.05 — Civilian unemployment rate
- GET /v1/fred/vix — $0.05 — CBOE Volatility Index: VIX

### macro

- GET /v1/macro/bundle — $0.10 — Macro Bundle: Treasury + CPI + GDP + Employment + Fed Funds + M2 + VIX + Trade (single call)
- GET /v1/macro/recession-probability — $0.10 — Recession Probability Index: yield curve spread + unemployment + leading indicators
- GET /v1/macro/snapshot/all — $0.05 — Complete macro snapshot: GDP, CPI, UNRATE, yields, VIX

### treasury

- GET /v1/treasury/auction-results/recent — $0.05 — Recent Treasury auction results
- GET /v1/treasury/tips-rates/current — $0.05 — Current TIPS rates (5, 7, 10, 20, 30-year)
- GET /v1/treasury/yield-curve/daily-snapshot — $0.05 — U.S. Treasury yield curve (FRED-sourced, 11 maturities)
- POST /v1/treasury/yield-curve/historical — $0.05 — Historical yield curve data (max 90-day range)

### yield-spread

- GET /v1/yield-spread/10y-2y — $0.05 — 10-year minus 2-year Treasury yield spread
- GET /v1/yield-spread/10y-3m — $0.05 — 10-year minus 3-month Treasury yield spread
- GET /v1/yield-spread/10y-5y — $0.05 — 10-year minus 5-year Treasury yield spread
- GET /v1/yield-spread/30y-5y — $0.05 — 30-year minus 5-year Treasury yield spread
- GET /v1/yield-spread/5y-2y — $0.05 — 5-year minus 2-year Treasury yield spread