# Brazil Macro AI

> Brazil Macroeconomic and Financial Data AI Platform — deterministic,
> point-in-time Brazilian macro/rates capabilities for AI agents, over
> REST and MCP, with per-call x402 (USDC on Base) payment for paid
> capabilities.

Brazil Macro AI computes Brazilian policy-rate, yield-curve, inflation,
and macro-release capabilities directly from public primary sources
(BCB, B3, IBGE, Tesouro Direto) using versioned, documented methods —
never a scraped or resold third-party feed, never a Bloomberg-equivalent
claim. Every response carries provenance (source, method_id,
calculation_version) and a point-in-time `as_of` date; historical
queries return what was known/published as of that date, never
retroactively revised data presented as if it were known earlier.

## Endpoints

- API base: https://api.brazilmacro.com/v1
- MCP (streamable HTTP, stateless): https://api.brazilmacro.com/mcp
- OpenAPI spec: https://api.brazilmacro.com/openapi.json
- Interactive docs: https://api.brazilmacro.com/docs
- Capability manifest (machine-readable): https://api.brazilmacro.com/v1/capabilities
- Health: https://api.brazilmacro.com/health/live , https://api.brazilmacro.com/health/ready

## Payment (x402)

Paid capabilities return HTTP 402 with a `Payment-Required` header
(x402 v2, scheme `exact`) when called without payment. Pay with USDC on
Base mainnet:

- Protocol: x402, version 2
- Scheme: exact
- Network: eip155:8453 (Base mainnet)
- Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Recipient: 0x3f784488af70516fa9d23a7bcc1eff3b5ad3c9ab
- Price: see per-capability price below, or the live `price_usd` field
  at https://api.brazilmacro.com/v1/capabilities (source of truth —
  prices below are a snapshot, not authoritative)

MCP tool calls carry the signed payment via the tool call's `_meta`
field under the key `x402/payment`, per the MCP request-metadata
mechanism. REST calls carry it via the `Payment-Signature` header.

## Capabilities (pricing_version v1.0)

Free:
- `brazil_selic_snapshot` — $0.00 — current Selic target, realized
  Selic 252 / CDI, and the last Copom decision. GET /v1/rates/selic
- `brazil_macro_actual` — $0.00 — headline Brazilian macro actuals
  (IPCA, IPCA-15, GDP, PIM-PF, PMC, PMS, PNAD unemployment) with a
  release/vintage layer. GET /v1/brazil/macro/actual
- `brazil_macro_calendar` — $0.00 — official IBGE release calendar,
  scheduled → released → corrected status. GET /v1/brazil/macro/calendar

Paid:
- `brazil_yield_curve` — $0.01 — nominal Brazilian sovereign
  zero-coupon curve, bootstrapped from Tesouro Direto LTN/NTN-F.
  GET /v1/brazil/yield-curve
- `brazil_real_curve` — $0.03 — real (IPCA-linked) sovereign
  zero-coupon curve from NTN-B/NTN-B Principal. GET /v1/brazil/real-curve
- `brazil_inflation_breakeven` — $0.03 — market-implied inflation
  breakeven via Fisher's exact identity from the nominal/real curves.
  GET /v1/brazil/inflation-breakeven
- `brazil_focus_revisions` — $0.05 — detects and measures the speed of
  BCB Focus survey revisions (Selic, IPCA, PIB, Câmbio).
  GET /v1/brazil/focus/revisions
- `brazil_macro_surprise` — $0.05 — actual vs. pre-release consensus
  (currently wired for IPCA only). GET /v1/brazil/macro/surprise
- `brazil_copom_path` — $0.10 — market-implied Selic path for the next
  1-8 Copom meetings, from B3 DI1 futures (like CME FedWatch, for
  Brazil). GET /v1/rates/copom-path
- `brazil_market_vs_focus` — $0.15 — market-implied Copom path vs. the
  Focus survey median, meeting-by-meeting gap in bps.
  GET /v1/rates/market-vs-focus
- `brazil_monetary_policy_divergence` — $0.25 — composite divergence
  across market pricing, Focus survey, breakevens, and macro surprises.
  GET /v1/brazil/monetary-policy-divergence

## Methodology and limitations

- `brazil_yield_curve` / `brazil_real_curve` are bootstrapped from
  retail-offered Tesouro Direto securities (ODbL public data) — this is
  NOT an institutional ANBIMA or Bloomberg curve; do not treat it as
  equivalent to one.
- Every response includes `method_id` and `calculation_version` for
  exact reproducibility, and a `quality_status` / `freshness` field —
  never silently interpolated or extrapolated beyond documented node
  coverage (returns `status="unsupported"` instead).
- `brazil_focus_revisions` covers Selic, IPCA, PIB Total, and Câmbio
  only. `brazil_macro_surprise` covers IPCA only (no consensus wired
  for other indicators yet).
- Full per-capability usage guidance (when to use / when not to) is in
  the live manifest at /v1/capabilities.

## For agent developers

Full OpenAPI 3.1 schema: https://api.brazilmacro.com/openapi.json
MCP tool list: call `tools/list` on https://api.brazilmacro.com/mcp