# 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. Most endpoints are 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). Four endpoints are DETERMINISTIC PRIMITIVES — no LLM is involved at all. They return the identical answer for identical inputs, are cheap, and are meant to be called in a loop rather than sampled once: - GET /api/fx/convert — official ECB reference rates ($0.005) - GET /api/market/is-open — global exchange trading calendar ($0.005) - GET /api/macro/us — official US GDP / PCE inflation / SOFR, read on-chain ($0.01) - GET /api/macro/us-revisions — the immutable revision trail of any of those series ($0.02) - GET /api/cot — CFTC Commitments of Traders: hedge-fund/speculator positioning, 21 markets, WoW deltas ($0.02) The two /api/macro/ endpoints are INDEPENDENTLY VERIFIABLE. They are not our opinion of the data and not a model's recollection of it: they are a plain `eth_call` against a Chainlink aggregator contract, and every value we return ships with the contract address and round ID it was decoded from. You can check any answer yourself with one permissionless, keyless read. No LLM endpoint anywhere can offer that. ## 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), 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) + CoinGecko + GDELT + 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/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?group={fx|commodities|grains|financials|all} - Returns: net speculator/managed-money/leveraged-fund positioning per market with week-over-week deltas and a computed bias — deterministic, no LLM - fx: EUR/USD, GBP/USD, USD/JPY, AUD/USD, USD/CAD, USD/CHF, NZD/USD (CME legacy non-commercial nets) - commodities: Gold (COMEX), WTI-Physical (NYMEX) - grains: corn, wheat SRW, soybeans, soybean oil, soybean meal, natgas (disaggregated managed-money) - financials: E-Mini S&P 500, NASDAQ, Dow, Russell 2000, UST Bond, UST 10Y (TFF leveraged funds + asset managers) - Price: $0.02 - Data: CFTC Public Reporting API (public domain). Published Fridays ~15:30 ET for Tuesday positions. 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 ## Deterministic Primitives (no LLM — same input, same output, every time) GET /api/fx/convert?from={USD}&to={EUR,GBP,JPY}&amount={1}&date={YYYY-MM-DD} - Answers: "what is the USD to EUR exchange rate", "convert 250 GBP to JPY", "what was the EUR/USD FX rate on 2024-03-15" - Returns: { from, to: { EUR: { rate, amount } }, amount_in, date, is_last_available_fixing, source, deterministic, cache_hint_seconds } - `date` is the ECB fixing date ACTUALLY used. The ECB fixes only on TARGET business days, so a weekend/holiday request carries the previous fixing and is_last_available_fixing=true tells you so. - Multi-currency in one call. 30+ currencies. Historical fixings back to 1999-01-04. - Data: European Central Bank daily reference rates (via Frankfurter). Keyless. No model estimate anywhere in the path. - Unknown currency codes return 422 with the supported list — never a silently missing key. - Price: $0.005 GET /api/market/is-open?exchange={NYSE}&at={ISO-8601} - Answers: "is the stock market open right now", "is NYSE open", "what are LSE trading hours", "when does the Tokyo market next open", "is the market closed for a holiday today" - Exchanges: NYSE, NASDAQ, LSE, XETRA, EURONEXT, SIX, JPX (TSE), HKEX, SSE, ASX, TSX, NSE, BSE. Aliases accepted (TSE, XNYS, FRANKFURT, NIFTY, SENSEX, ...). - Returns: { exchange, name, timezone, is_open, status, local_time, next_open, next_close, holiday, session, calendar_coverage_until, deterministic } - status: open | pre_market | after_hours | lunch_break | closed_weekend | closed_holiday - `at` lets an agent ask about any past or future moment, not just now. - ZERO external calls. Built-in trading calendar: regular sessions, lunch breaks (JPX/HKEX/SSE), half-days, and holiday tables checked against each venue's own published calendar. - HONESTY: every exchange declares calendar_coverage_until. Past that date we return 422 beyond_calendar_coverage rather than guess. HKEX, SSE, ASX, TSX, EURONEXT and NSE/BSE have not published 2027, so they stop at 2026-12-31. NYSE, NASDAQ, LSE, XETRA, SIX and JPX run to 2027-12-31. - Price: $0.005 GET /api/macro/bls-series?series={cpi,unemployment} - Answers: "what is US CPI right now", "current US unemployment rate", "US wage growth YoY", "JOLTS job openings", "any BLS series by id" - DETERMINISTIC PRIMITIVE (no LLM): up to 5 BLS series per call, by alias (cpi, cpi-core, unemployment, nonfarm-payrolls, wages, job-openings, eci, ppi) or ANY raw BLS series id (state unemployment, metro CPI, industry wages — the id printed on every bls.gov table) - Returns per series: latest value + period, same-period year-ago value, computed YoY change and percent (never diffed across mismatched periods), and the last 13 observations - Unknown/invalid series ids 404 BEFORE payment settles; a BLS outage is an honest 502, never a fake number - Straight from the primary source (api.bls.gov) — no FRED, no intermediary. License: public domain (US federal government work). - Price: $0.02 GET /api/macro/us?series={gdp_change,sofr} - Answers: "what is US GDP growth", "current US inflation PCE", "what is SOFR today", "official US economic data", "BEA macro statistics", "is the US economy growing" - Seven series, all read directly from Chainlink aggregator contracts: gdp_level Real GDP — Level billions of chained 2017 dollars Base gdp_change Real GDP — Percent Change (Annual Rate) percent, annualised Base pce_level PCE Price Index — Level index Base pce_change PCE Price Index — Percent Change (Ann.) percent, annualised Base rfs_level Real Final Sales to Private Dom. Purchasers billions of chained 2017 dollars Base rfs_change Real Final Sales — Percent Change (Ann.) percent, annualised Base sofr Secured Overnight Financing Rate percent Ethereum - Returns per series: { key, name (the contract's own description()), value, units, as_of, round_id, contract, chain, publisher, stale, error } - TWO CHAINS, ONE ANSWER. The six BEA series live on Base (eip155:8453); SOFR lives on Ethereum mainnet (eip155:1). No single chain has the whole picture, and you would have to already know that to assemble it. We do the cross-chain assembly. - PUBLISHERS ARE NOT INTERCHANGEABLE. The six GDP/PCE/final-sales series are U.S. Bureau of Economic Analysis (Department of Commerce). SOFR is the Federal Reserve Bank of New York. Each series names its own publisher; we do not file them all under one agency. - VERIFY US. The response carries a `verify` block with the contract address and the selectors (latestRoundData 0xfeaf968c, decimals 0x313ce567, description 0x7284e416). Call them yourself — reads are free, permissionless, and need no API key. Take the int256 answer, divide by 10**decimals(), and you get exactly the number we gave you. - NULL, NEVER ZERO. If a feed cannot be read (public RPCs rate-limit hard) the value is `null` with an explicit error — never a 0, and never a model estimate. A zero here is a number you might trade on. - These are on-chain Data Feeds, not Chainlink Data Streams. No key, no subscription, no expiry. - License: public domain (US federal government work). Deterministic. No LLM. - Price: $0.01 GET /api/macro/us-revisions?series={gdp_change}&limit={8} - Answers: "has US GDP been revised", "what was GDP first reported as", "how much did BEA revise Q1 GDP", "US GDP revision history", "was the inflation number revised" - THE POINT: BEA revises every estimate — advance, then second, then third — and the Chainlink aggregator's round history captures every one of those revisions immutably, with a timestamp. Anyone can tell you US GDP grew 2.1%. This tells you it was first printed at 1.4%, cut to 0.5%, then revised to 2.1%, exactly when each landed, and gives you the round ID to prove it. - series: gdp_level, gdp_change, pce_level, pce_change, rfs_level, rfs_change, sofr. Default gdp_change. - limit: prints to walk back, 1-24. Default 8. - Returns: { key, name, trail_semantics, prints[{ round_id, phase, value, as_of, revision_from_previous }], latest_vs_first, history_method, trail_is_reliable, errors, verify } - trail_semantics is honest about what a step MEANS: BEA quarterly series give `revisions` (successive estimates of the same figure). SOFR gives `daily_prints` — a day-over-day move in an overnight rate is not a "revision" of anything, and we do not dress it up as one. - PHASE BOUNDARIES ARE HANDLED. roundId is a packed uint80 (phase << 64 | aggregatorRoundId). Naively decrementing it works within a phase and then falls off a cliff — on gdp_change the live phase holds only FIVE rounds, so a naive walk returns five prints and silently hides a year of history. We resolve earlier phases via phaseAggregators(uint16) and keep walking, and we report which phases were walked. - MIGRATION DUPLICATES ARE COLLAPSED. During an aggregator migration Chainlink writes the same print to both the old and the new aggregator, sometimes seconds apart. We drop the duplicate (keeping the live aggregator's copy) so you never see a phantom "revision" from 2.0 to 2.0, and we tell you how many we dropped in phase_overlap_deduped. - A THROTTLED READ IS NOT "NEVER REVISED". If any round could not be read, trail_is_reliable=false and `errors` says which. We never let a rate-limited walk masquerade as the end of history, and we return an error rather than an empty trail — an empty trail would read as "this figure was never revised", which is a far more dangerous claim. - Every print carries its round_id: call getRoundData(uint80) (0x9a6fc8f5) on the contract and check any step yourself. - Deterministic. No LLM. No API key. - Price: $0.02 ## 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