# Macro Analyst
> Deterministic macro-economic analysis toolkit — yield-curve, breakeven-inflation, growth, inflation-decomposition, FX, rates-math and real-commodity compute operations behind x402 micropayments, with a machine-readable macro-analyst persona.

A neutral, deterministic macro-analysis backend usable by any agentic AI. It exposes granular compute operations (yield-curve spreads, breakeven inflation, growth/SAAR, inflation decomposition, FX/carry, generic macro stats, rates math, real commodity prices) that the driving agent feeds its own data into, plus a single-call /ma/ask orchestration endpoint. Compute-only by design: data acquisition stays with the caller, every computed number comes from the deterministic engine, and the persona's hard rule is that no LLM arithmetic ever substitutes for it.

## Adopting the persona
GET `/persona` to retrieve the machine-readable SOUL and adopt it as a temporary role/skill. Authored SOUL (adapted from the default macro-analyst hermes profile) shipped at /persona; the deterministic rules below are the machine-readable mirror of its hard-rule section.

## Pricing
- `basic` tier — **$0.006125** on Base: `/ma/yield_curve`, `/ma/breakeven_inflation`, `/ma/growth`, `/ma/inflation_decomp`, `/ma/fx`, `/ma/macro_stats`, `/ma/rates_math`, `/ma/real_commodity`, `/ma/validate`, `/ma/knowledge`, `/ma/sources`
- `exclusive` tier — **$0.256125** on Base: `/ma/ask`
- Chains: Base, Arbitrum, Polygon, Avalanche, Ethereum. Per-chain prices in `/.well-known/x402.json`.

## Operations
### compute
- **POST /ma/yield_curve** — Yield-curve level, spreads (2s10s/3m10s/3m2s/10s30s), shape label, and — with a prior curve — per-tenor shift and steepener change. Caller supplies the curve. — params: `curve` (object)*, `prior` (object) (tier: `basic`)
- **POST /ma/breakeven_inflation** — Breakeven inflation (nominal minus real yield) per tenor, 5y5y forward from 5y/10y BEI, real yields, and an expectations label. Caller supplies nominal/real yield pairs. — params: `pairs` (object)* (tier: `basic`)
- **POST /ma/growth** — Growth rates from a series: YoY, period-over-period, annualized (SAAR), trailing-average YoY, and a window trend. Caller supplies the series. — params: `series` (object)*, `assumptions` (object) (tier: `basic`)
- **POST /ma/inflation_decomp** — Headline/core CPI decomposition: headline-core gap, MoM annualized, 3m/6m/12m annualized, base effect, and per-component contributions. Caller supplies the monthly series. — params: `data` (object)* (tier: `basic`)
- **POST /ma/fx** — FX math from caller-supplied inputs: % change vs a prior spot, annualized carry (rate differential), and a real-FX proxy (spot x CPI ratio) with its % change. — params: `inputs` (object)* (tier: `basic`)
- **POST /ma/macro_stats** — Generic deterministic stats on a series: pct change, YoY, window z-score + percentile rank, max drawdown, CAGR. Caller supplies the series. — params: `series` (object)*, `assumptions` (object) (tier: `basic`)
- **POST /ma/rates_math** — Rates math from two yields/tenors: implied forward rate, zero-coupon modified duration, and DV01 for $100 face. Yields in decimals, tenors in years. — params: `inputs` (object)* (tier: `basic`)
- **POST /ma/real_commodity** — Real (deflated) commodity price: price/cpi, real return vs a prior observation, and % off an all-time real peak. Caller supplies price + CPI. — params: `inputs` (object)* (tier: `basic`)

### validate
- **POST /ma/validate** — Validate an input document against the canonical schema (series/curve/pairs/fx/commodity/rates) — correct the request before paying for compute. — params: `document` (object)*, `kind` (string)* (tier: `basic`)

### assembly
- **POST /ma/ask** — One-call structured macro analysis. DeepSeek orchestrates the deterministic compute operations (supplying its own data) and returns a structured brief (bottom line, rates, inflation, growth, cross-asset, risks). — params: `question` (string)*, `messages` (array) (tier: `exclusive`)

### helper
- **POST /ma/knowledge** — Retrieve the service's methodology corpus (determinism contract, macro framework, release-calendar workflows, source registry). — params: `query` (string)*, `limit` (integer) (tier: `basic`)
- **POST /ma/sources** — List the service's recommended (keyless) data sources and their reliability ratings, for the caller to acquire its own data. (tier: `basic`)

## Workflows
- **rates-snapshot** (yield-curve + inflation expectations read): `yield_curve -> breakeven_inflation -> rates_math` — supply the curve + TIPS pairs; lead with shape and 5y5y
- **inflation-deep-dive** (headline vs core, base effects, momentum): `inflation_decomp -> macro_stats` — monthly CPI series; report MoM/3m/6m/12m annualized + base effect
- **growth-read** (growth momentum + trend): `growth -> macro_stats` — quarterly for SAAR; check YoY vs trend
- **cross-asset-read** (FX + real-commodity context): `fx -> real_commodity -> yield_curve` — carry + real FX + deflated commodity prices
- **full-brief** (one-call structured macro brief): `ma_ask` — DeepSeek acquires data and orchestrates the compute ops

## Deterministic contract
- No LLM arithmetic: every computed number comes from a compute operation.
- Cross-verify 2s10s vs 3m10s + (2s10s - 3m10s).
- Cross-verify breakeven inflation vs nominal > real (typical).

## Data sources
- FRED fredgraph.csv (FRED) — keyless: DGS2/10/30, DFII10, CPIAUCSL/CPILFESL, PCE, GDP, M2
- Yahoo v8 chart (Yahoo Finance) — keyless: ^TNX/^FVX/^TYX/^IRX/^VIX, indices, FX, GC=F, CL=F/BZ=F
- Google News RSS (Google News) — headlines; prefer when:ND filter
- FXStreet RSS (FXStreet) — FX/macro news; JSON-LD articleBody extraction
- Central bank pages (Fed/ECB/BoJ/BoE/RBI) — statements, votes, release calendars

## Free endpoints
- GET `/`, `/health`, `/about`, `/.well-known/x402.json`, `/llms.txt`, `/openapi.json` (standard)
- GET `/ma/tools` — list all operations with input schemas
- GET `/macro-analyst/feedback` — 50 most recent feedback entries
- POST `/macro-analyst/feedback` — submit feedback

## Examples
- `rates-snapshot` — yield-curve + inflation expectations read: `{"curve": {"tenors": ["3M", "2Y", "5Y", "10Y", "30Y"], "yields": [0.043, 0.044, 0.0435, 0.0432, 0.0445]}}`
- `breakeven_inflation` — inflation expectations: `{"pairs": {"tenors": ["5Y", "10Y"], "nominal_yields": [0.042, 0.0432], "real_yields": [0.021, 0.0205]}}`
- `growth` — quarterly growth momentum: `{"series": {"values": [100.0, 100.8, 101.7, 102.6, 103.4], "periodicity": "quarterly"}}`