# MacroPulse

> Real-time macro intelligence API for forex and CFD traders. Session briefs, COT positioning (currencies + gold/WTI), commodity prices (gold/silver/WTI/Brent/natural gas/copper), economic events, equity indices, economic calendar, and directional sentiment — all via x402 micropayments on Base. G10 coverage with PBoC CNY fix context for Asian session.

## What This Is

MacroPulse is a pay-per-query API that synthesizes live economic data, institutional positioning, and real-time news into structured, actionable intelligence for forex and CFD traders.

Every response is generated by Claude using live data from FRED (Federal Reserve), CFTC (COT reports), Alpha Vantage (equity indices), EIA (petroleum inventory), CoinGecko (crypto), and Tavily (real-time news).

## Payment

All endpoints require x402 micropayment (USDC on Base mainnet).
Protocol: x402 | Network: eip155:8453 | Asset: USDC
Payment address: 0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc

To use: send a GET request without a PAYMENT-SIGNATURE header to receive a 402 response with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header.

## Endpoints

GET /api/session-brief?session={asian|london|newyork}
- Returns: forex session intelligence — risk tone, top pair biases, scheduled events, rates snapshot (including PBoC CNY fix for Asian session), equity context, crypto context, agent action
- Asian session: includes USD/CNY PBoC daily fixing level — stronger-than-expected fixing = CNY strength = positive for AUD, NZD, EM
- Data: FRED (USD/CNY + rates) + Alpha Vantage + CoinGecko + Tavily
- Price: $0.10
- Session auto-detected from UTC time if omitted

GET /api/event-pulse?event={NFP|CPI|FOMC|GDP|PPI|PCE|ISM|JOLTS|ECB|BOJ|BOE|RBA|RBNZ|BOC}
- Returns: economic event deep-dive — forecast vs consensus, historical context, forex market impact, agent action
- Price: $0.20

GET /api/crypto-pulse
- Returns: BTC/ETH snapshot, Fear & Greed index, market dominance, macro link to traditional markets
- Data: CoinGecko + alternative.me
- Price: $0.05

GET /api/commodities-pulse
- Returns: gold, silver, WTI, Brent, natural gas (Henry Hub + EU TTF context), copper — prices, posture, Brent/WTI spread, forex impact on AUD/CAD/NOK/JPY/EUR
- copper is synthesized from news (LME/COMEX) — Dr. Copper is the leading global growth indicator; primary driver is China demand
- natural_gas includes EU TTF context when relevant — European gas prices diverge significantly from US Henry Hub
- Data: FRED (gold/silver/WTI/Brent/Henry Hub) + Tavily (copper + global context)
- Price: $0.10

GET /api/equities-pulse?session={asian|london|newyork}
- Returns: global equity index snapshot — S&P 500, Nasdaq, Dow (via Alpha Vantage EOD) + international context, risk tone, forex impact
- Price: $0.10

GET /api/calendar
- Returns: weekly economic calendar — high-impact events, central bank schedule, peak volatility windows, agent action
- Data: Tavily synthesis
- Price: $0.10

GET /api/cot
- Returns: CFTC Commitment of Traders positioning for 7 major currency pairs PLUS gold futures and WTI crude oil futures
- Currency pairs: EUR/USD, GBP/USD, USD/JPY, AUD/USD, USD/CAD, USD/CHF, NZD/USD
- Commodity futures: Gold (XAU) net speculator longs/shorts, WTI crude net speculator longs/shorts
- Includes: net speculator positions, week-over-week change, extreme/crowded trade flags, contrarian alerts, commodity_positioning section
- Data: CFTC Socrata API (free, no key required)
- Price: $0.15

GET /api/eia-inventory
- Returns: EIA weekly petroleum inventory — crude oil, gasoline, distillate stocks, draw/build direction, WTI impact, forex impact on CAD/NOK
- Data: EIA + Tavily
- Price: $0.10

GET /api/sentiment?pair={EURUSD|GBPUSD|USDJPY|...}
- Returns: directional sentiment for any forex pair — score 0-100, components (news tone, technical bias, risk environment, momentum), key level, catalyst, agent action
- Price: $0.05

## Discovery

- OpenAPI spec: https://macropulse.theaslangroupllc.com/openapi.json
- Agent discovery: https://macropulse.theaslangroupllc.com/.well-known/agent.json

## Notes for AI Agents

- All endpoints return structured JSON
- Disclaimer is appended automatically to every response
- FRED data activates automatically when FRED_API_KEY is set — degrades gracefully without it
- EIA data activates automatically when EIA_API_KEY is set — degrades gracefully without it
- COT data requires no API key (CFTC Socrata is public)
- Crypto and Fear & Greed data require no API key