{ "openapi": "3.1.0", "info": { "title": "MacroPulse API", "description": "Real-time macro intelligence for forex and CFD traders. All endpoints require x402 payment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.", "version": "1.1.0", "contact": { "url": "https://macropulse.theaslangroupllc.com" } }, "servers": [ { "url": "https://macropulse.theaslangroupllc.com" } ], "paths": { "/api/session-brief": { "get": { "summary": "Forex session brief", "description": "Real-time macro intelligence for the current or specified trading session. Includes rates snapshot, top pair biases, scheduled events, and agent action.", "operationId": "sessionBrief", "parameters": [ { "name": "session", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asian", "london", "newyork" ] }, "description": "Trading session. Auto-detected from UTC time if omitted." } ], "responses": { "200": { "description": "Session brief", "content": { "application/json": { "schema": { "type": "object", "properties": { "headline": { "type": "string" }, "risk_tone": { "type": "string", "enum": [ "risk-on", "risk-off", "neutral" ] }, "session": { "type": "string" }, "top_pairs": { "type": "array" }, "scheduled_events": { "type": "array" }, "rates_snapshot": { "type": "object" }, "crypto_context": { "type": "string" }, "narrative": { "type": "string" }, "agent_action": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required. See PAYMENT-REQUIRED response header for x402 payment details.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded x402 payment requirements" } } } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/event-pulse": { "get": { "summary": "Economic event deep-dive", "description": "Deep analysis of a specific economic event — forecast vs consensus, historical context, forex market impact.", "operationId": "eventPulse", "parameters": [ { "name": "event", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "NFP", "CPI", "FOMC", "GDP", "PPI", "PCE", "ISM", "JOLTS", "RETAIL_SALES", "UNEMPLOYMENT", "ECB", "BOJ", "BOE", "RBA", "RBNZ", "BOC" ] }, "description": "Economic event identifier" } ], "responses": { "200": { "description": "Event analysis" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.2, "x-agent-use-case": "on-demand" } }, "/api/crypto-pulse": { "get": { "summary": "Crypto market context", "description": "BTC and ETH prices, market cap, dominance, Fear & Greed index, and risk tone for forex context.", "operationId": "cryptoPulse", "responses": { "200": { "description": "Crypto snapshot" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.05, "x-agent-use-case": "on-demand" } }, "/api/commodities-pulse": { "get": { "summary": "Commodities brief", "description": "Gold, silver, WTI, and Brent crude — current prices (via FRED when available), posture, Brent/WTI spread, and forex impact on commodity-linked currencies.", "operationId": "commoditiesPulse", "responses": { "200": { "description": "Commodities brief" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/calendar": { "get": { "summary": "Weekly economic calendar", "description": "High-impact economic events for the current trading week — dates, times, currency impact, central bank schedule, and peak volatility windows.", "operationId": "calendar", "responses": { "200": { "description": "Weekly calendar" }, "402": { "description": "Payment required" } }, "x-price-usd": 0.1, "x-agent-use-case": "on-demand" } }, "/api/cot": { "get": { "summary": "CFTC Commitments of Traders positioning — 21 markets, deterministic", "description": "Speculator/hedge-fund positioning parsed from the CFTC Socrata datasets. Groups: fx (7 CME pairs), commodities (gold, WTI), grains (managed-money: corn, wheat, soy complex, natgas), financials (TFF leveraged-fund + asset-manager nets: S&P, NASDAQ, Dow, Russell, T-Bond, 10Y). Net positions, WoW deltas, computed bias. No LLM. Fridays for Tuesday positions.", "x-agent-use-case": "on-demand", "parameters": [], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.02 } }, "/api/eia-inventory": { "get": { "summary": "Weekly EIA petroleum inventory intelligence for energy and macro agents — crude, gasoline and distillate builds and draws versus expectations, with the oil-price and CAD/NOK implications.", "description": "Weekly EIA petroleum inventory intelligence for energy and macro agents — crude, gasoline and distillate builds and draws versus expectations, with the oil-price and CAD/NOK implications.", "x-agent-use-case": "on-demand", "parameters": [], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.1 } }, "/api/intermarket": { "get": { "summary": "Cross-asset intermarket synthesis for macro agents — bond yields, equities, commodities and FX read together to surface the dominant regime and the divergences that tend to lead price.", "description": "Cross-asset intermarket synthesis for macro agents — bond yields, equities, commodities and FX read together to surface the dominant regime and the divergences that tend to lead price.", "x-agent-use-case": "on-demand", "parameters": [], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.15 } }, "/api/rates-differential": { "get": { "summary": "Interest-rate differential and carry intelligence for FX agents — G10 policy rates, yield spreads and the carry-trade map that drives durable currency trends.", "description": "Interest-rate differential and carry intelligence for FX agents — G10 policy rates, yield spreads and the carry-trade map that drives durable currency trends.", "x-agent-use-case": "on-demand", "parameters": [], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.1 } }, "/api/regime": { "get": { "summary": "Macro regime classifier for multi-asset agents — labels the current environment (risk-on/off, reflation, stagflation, tightening) and its directional implications for FX, rates and equities.", "description": "Macro regime classifier for multi-asset agents — labels the current environment (risk-on/off, reflation, stagflation, tightening) and its directional implications for FX, rates and equities.", "x-agent-use-case": "on-demand", "parameters": [], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.1 } }, "/api/sentiment": { "get": { "summary": "Real-time directional sentiment for any forex pair or gold — retail crowd positioning, COT institutional alignment, and a clear contrarian bias call. Built for FX trading and advisor agents.", "description": "Real-time directional sentiment for any forex pair or gold — retail crowd positioning, COT institutional alignment, and a clear contrarian bias call. Built for FX trading and advisor agents.", "x-agent-use-case": "on-demand", "parameters": [ { "name": "pair", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid macro intelligence response (JSON)." }, "402": { "description": "Payment required — x402 USDC on Base." } }, "x-price-usd": 0.05 } }, "/api/fx/convert": { "get": { "summary": "Currency conversion at the official ECB reference rate", "description": "Convert an amount between currencies at the official European Central Bank reference rate. 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\". Multi-currency in one call (to=EUR,GBP,JPY), 30+ currencies, historical daily fixings back to 1999. Deterministic and cacheable: real ECB data, not a model estimate - identical inputs always return the identical rate. Keyless, sub-second, no LLM.", "operationId": "fxConvert", "x-agent-use-case": "high-frequency", "x-deterministic": true, "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "USD" }, "description": "Source currency, ISO 4217 alpha-3." }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "EUR,GBP" }, "description": "Target currency, or a comma-separated list (max 30)." }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "number", "default": 1 }, "description": "Amount to convert. Default 1 (the raw rate)." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-03-15" }, "description": "YYYY-MM-DD. Returns that day's ECB fixing, or the last fixing on or before it (whose date is reported back in `date`, with is_last_available_fixing=true). Omit for the latest." } ], "responses": { "200": { "description": "Conversion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "amount_in": { "type": "number" }, "to": { "type": "object", "additionalProperties": { "type": "object", "properties": { "rate": { "type": "number" }, "amount": { "type": "number" } } } }, "date": { "type": "string", "description": "The ECB fixing date actually used." }, "requested_date": { "type": [ "string", "null" ] }, "is_last_available_fixing": { "type": "boolean" }, "source": { "type": "string" }, "deterministic": { "type": "boolean" }, "cache_hint_seconds": { "type": "integer" } } } } } }, "402": { "description": "Payment required - x402 USDC on Base or Solana." }, "422": { "description": "unsupported_currency | invalid_currency | invalid_date | invalid_amount | no_fixing" }, "502": { "description": "source_unavailable - the ECB fixing could not be read. No rate is estimated." } }, "x-price-usd": 0.005 } }, "/api/market/is-open": { "get": { "summary": "Is the stock market open right now? Exchange status, trading hours and holiday calendar", "description": "Is the stock market open right now? Deterministic market-status and trading-hours check for the major global exchanges - NYSE, NASDAQ, LSE, Xetra, Euronext, TSE/JPX, HKEX, SSE, ASX, TSX, SIX, NSE and BSE. Returns is_open plus why it is shut (weekend, exchange holiday, lunch break, pre-market, after-hours), the exchange local time, the named holiday, and the next market open and next close as ISO timestamps. Pass ?at= to ask about any past or future moment. ZERO external calls, no LLM, sub-second, cacheable.", "operationId": "marketIsOpen", "x-agent-use-case": "high-frequency", "x-deterministic": true, "parameters": [ { "name": "exchange", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "NYSE", "NASDAQ", "LSE", "XETRA", "EURONEXT", "SIX", "JPX", "HKEX", "SSE", "ASX", "TSX", "NSE", "BSE" ] }, "description": "Exchange code. Aliases accepted (TSE->JPX, XNYS->NYSE, FRANKFURT->XETRA, ...)." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-12-25T14:30:00Z" }, "description": "ISO 8601 timestamp to evaluate. Default: now." } ], "responses": { "200": { "description": "Market status", "content": { "application/json": { "schema": { "type": "object", "properties": { "exchange": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "at": { "type": "string" }, "local_time": { "type": "string" }, "is_open": { "type": "boolean" }, "status": { "type": "string", "enum": [ "open", "pre_market", "after_hours", "lunch_break", "closed_weekend", "closed_holiday" ] }, "holiday": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "date": { "type": "string" } } }, "session": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" }, "half_day": { "type": "boolean" }, "lunch_break": { "type": "boolean" } } }, "next_open": { "type": [ "string", "null" ] }, "next_close": { "type": [ "string", "null" ] }, "calendar_coverage_until": { "type": "string" }, "deterministic": { "type": "boolean" } } } } } }, "402": { "description": "Payment required - x402 USDC on Base or Solana." }, "422": { "description": "unsupported_exchange | invalid_timestamp | beyond_calendar_coverage (we refuse to guess holidays past the venue’s published calendar)" } }, "x-price-usd": 0.005 } }, "/api/macro/us": { "get": { "summary": "Official US macro indicators read from Chainlink contracts (GDP, PCE, SOFR)", "description": "Official US macroeconomic data read directly from Chainlink aggregator contracts on-chain. No LLM, no API key, no vendor, no terms of service. Answers \"what is US GDP growth\", \"current US inflation PCE\", \"what is SOFR today\", \"official US economic data\", \"BEA macro statistics\". Seven series: real GDP (level + growth), PCE price index (level + inflation), real final sales to private domestic purchasers (level + growth), and SOFR. Six are published by the U.S. Bureau of Economic Analysis (Department of Commerce) and live on Base; SOFR is published by the Federal Reserve Bank of New York and lives on Ethereum mainnet - we do the cross-chain assembly. Every value ships with the contract address and round ID it was decoded from, so the answer can be independently verified against an immutable public ledger with a single permissionless eth_call. Deterministic and cacheable: identical inputs always return the identical value.", "operationId": "macroUsOnchain", "x-agent-use-case": "high-frequency", "x-deterministic": true, "x-verifiable-onchain": true, "parameters": [ { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "example": "gdp_change,sofr" }, "description": "Optional comma-separated filter. Any of: gdp_level, gdp_change, pce_level, pce_change, rfs_level, rfs_change, sofr. Omit for all seven." } ], "responses": { "200": { "description": "Decoded on-chain snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "gdp_level", "gdp_change", "pce_level", "pce_change", "rfs_level", "rfs_change", "sofr" ] }, "name": { "type": "string", "description": "The contract's own description()" }, "value": { "type": [ "number", "null" ], "description": "Scaled by the contract's own decimals(). NULL - never 0 - if the feed could not be read." }, "units": { "type": "string" }, "as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "The round's updatedAt" }, "round_id": { "type": [ "string", "null" ], "description": "Packed uint80: phase << 64 | aggregatorRoundId" }, "contract": { "type": "string" }, "chain": { "type": "string", "enum": [ "eip155:8453", "eip155:1" ] }, "publisher": { "type": "string" }, "stale": { "type": "boolean", "description": "True when served from cache after a live read failed" }, "error": { "type": [ "string", "null" ] } } } }, "source": { "type": "object", "description": "Publishers, transport, chains, license, verifiable" }, "verify": { "type": "object", "description": "Contract addresses and selectors so you can check every value yourself" }, "deterministic": { "type": "boolean" } } } } } }, "400": { "description": "Unknown series (paid request; no payment settled)" }, "402": { "description": "Payment required (x402)" }, "502": { "description": "No feed could be read from any RPC. A transport failure - never a zero." } } } }, "/api/macro/bls-series": { "get": { "summary": "US labor statistics by BLS series id — deterministic, computed YoY", "description": "Official US labor statistics straight from the primary source (api.bls.gov), deterministic. Up to 5 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. Returns per series: latest value and period, same-period year-ago value, computed year-over-year change and percent (never diffed across mismatched periods), and the last 13 observations. Unknown series ids return 404 before payment settles. No LLM, no key, public domain (US federal government work).", "operationId": "macroBlsSeries", "parameters": [ { "name": "series", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Up to 5 comma-separated BLS series ids or aliases", "example": "cpi,unemployment" } ], "responses": { "200": { "description": "Per-series latest value, year-ago value, computed YoY, and 13 observations" }, "400": { "description": "Invalid series parameter (no payment settled)" }, "402": { "description": "Payment required" }, "404": { "description": "BLS has no data for a requested series id (no payment settled)" }, "502": { "description": "BLS API unavailable or quota exhausted — transport failure, not a data statement" } }, "x-price-usd": 0.02, "x-agent-use-case": "component" } }, "/api/macro/us-revisions": { "get": { "summary": "The revision trail of a US macro series, from immutable on-chain round history", "description": "Has US GDP been revised? BEA revises every estimate (advance, then second, then third) and the Chainlink aggregator's round history captures every revision immutably, with a timestamp. Returns the ordered revision trail for a series: each print, when it landed, the change from the previous print, and a latest-vs-first summary. 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% - and hands you the contract address and round ID for every step, so you can verify each one against an immutable public ledger. Walks aggregator phase boundaries correctly (roundId is a packed uint80, so naive decrementing silently truncates history). No LLM, no API key. Deterministic.", "operationId": "macroUsRevisions", "x-agent-use-case": "high-frequency", "x-deterministic": true, "x-verifiable-onchain": true, "parameters": [ { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gdp_level", "gdp_change", "pce_level", "pce_change", "rfs_level", "rfs_change", "sofr" ], "default": "gdp_change" }, "description": "Which series to trace. Default gdp_change." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 8 }, "description": "How many prints to walk back. Default 8, max 24." } ], "responses": { "200": { "description": "Ordered revision trail, newest print first", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "gdp_level", "gdp_change", "pce_level", "pce_change", "rfs_level", "rfs_change", "sofr" ] }, "name": { "type": "string" }, "trail_semantics": { "type": "string", "enum": [ "revisions", "daily_prints" ], "description": "BEA quarterly series are genuine revisions of one estimate. SOFR rounds are simply the next day's rate, so they are labelled daily_prints rather than dressed up as revisions." }, "prints": { "type": "array", "items": { "type": "object", "properties": { "round_id": { "type": "string" }, "phase": { "type": "integer" }, "value": { "type": "number" }, "as_of": { "type": "string", "format": "date-time" }, "revision_from_previous": { "type": [ "number", "null" ], "description": "Change from the next older print. Computed in integer space, so 2.1 - 1.6 is exactly 0.5." } } } }, "latest_vs_first": { "type": [ "object", "null" ] }, "history_method": { "type": "object", "description": "phases_walked, complete_history, phase_overlap_deduped, cross_phase_walk" }, "trail_is_reliable": { "type": "boolean", "description": "False if any round could not be read. A short trail from throttling must never be read as \"never revised\"." }, "errors": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "object" }, "deterministic": { "type": "boolean" } } } } } }, "400": { "description": "Unknown series or out-of-range limit (paid request; no payment settled)" }, "402": { "description": "Payment required (x402)" }, "502": { "description": "Chain unreadable. Returns an error, never an empty trail - an empty trail would read as \"never revised\"." } } } } } }