openapi: 3.1.0 info: title: EconomicService API version: 1.0.0 paths: /api/economic/v1/get-fred-series: get: tags: - EconomicService summary: GetFredSeries description: GetFredSeries retrieves time series data from the Federal Reserve Economic Data. operationId: GetFredSeries parameters: - name: series_id in: query description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL"). required: false schema: type: string - name: limit in: query description: Maximum number of observations to return. Defaults to 120. required: false schema: type: integer format: int32 responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetFredSeriesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/list-world-bank-indicators: get: tags: - EconomicService summary: ListWorldBankIndicators description: ListWorldBankIndicators retrieves development indicator data from the World Bank. operationId: ListWorldBankIndicators parameters: - name: indicator_code in: query description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD"). required: false schema: type: string - name: country_code in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false schema: type: string - name: year in: query description: Optional year filter. Defaults to latest available. required: false schema: type: integer format: int32 - name: page_size in: query description: Maximum items per page. required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListWorldBankIndicatorsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-energy-prices: get: tags: - EconomicService summary: GetEnergyPrices description: GetEnergyPrices retrieves current energy commodity prices from EIA. operationId: GetEnergyPrices parameters: - name: commodities in: query description: Optional commodity filter. Empty returns all tracked commodities. required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEnergyPricesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-macro-signals: get: tags: - EconomicService summary: GetMacroSignals description: GetMacroSignals computes 7 macro signals from 6 upstream sources with BUY/CASH verdict. operationId: GetMacroSignals responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetMacroSignalsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-energy-capacity: get: tags: - EconomicService summary: GetEnergyCapacity description: GetEnergyCapacity retrieves installed capacity data (solar, wind, coal) from EIA. operationId: GetEnergyCapacity parameters: - name: energy_sources in: query description: |- Energy source codes to query (e.g., "SUN", "WND", "COL"). Empty returns all tracked sources (SUN, WND, COL). required: false schema: type: string - name: years in: query description: Number of years of historical data. Default 20 if not set. required: false schema: type: integer format: int32 responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEnergyCapacityResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-bis-policy-rates: get: tags: - EconomicService summary: GetBisPolicyRates description: GetBisPolicyRates retrieves central bank policy rates from BIS. operationId: GetBisPolicyRates responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetBisPolicyRatesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-bis-exchange-rates: get: tags: - EconomicService summary: GetBisExchangeRates description: GetBisExchangeRates retrieves effective exchange rates from BIS. operationId: GetBisExchangeRates responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetBisExchangeRatesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-bis-credit: get: tags: - EconomicService summary: GetBisCredit description: GetBisCredit retrieves credit-to-GDP ratio data from BIS. operationId: GetBisCredit responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetBisCreditResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-fred-series-batch: post: tags: - EconomicService summary: GetFredSeriesBatch description: GetFredSeriesBatch retrieves multiple FRED series in a single call. operationId: GetFredSeriesBatch requestBody: content: application/json: schema: $ref: '#/components/schemas/GetFredSeriesBatchRequest' required: true responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetFredSeriesBatchResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/list-grocery-basket-prices: get: tags: - EconomicService summary: ListGroceryBasketPrices description: ListGroceryBasketPrices retrieves grocery basket price comparison across 24 countries worldwide. operationId: ListGroceryBasketPrices responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListGroceryBasketPricesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/list-bigmac-prices: get: tags: - EconomicService summary: ListBigMacPrices description: ListBigMacPrices retrieves Big Mac Index prices across Middle East countries. operationId: ListBigMacPrices responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListBigMacPricesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-national-debt: get: tags: - EconomicService summary: GetNationalDebt description: GetNationalDebt retrieves national debt clock data for all countries. operationId: GetNationalDebt responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetNationalDebtResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/list-fuel-prices: get: tags: - EconomicService summary: ListFuelPrices description: ListFuelPrices retrieves retail gasoline and diesel prices across 30+ countries. operationId: ListFuelPrices responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListFuelPricesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-bls-series: get: tags: - EconomicService summary: GetBlsSeries description: GetBlsSeries retrieves BLS-only series not available on FRED (CES, LAUMT, CIU). operationId: GetBlsSeries parameters: - name: series_id in: query description: BLS series ID (e.g. "CES0500000001", "CIU1010000000000A"). required: false schema: type: string - name: limit in: query description: Maximum number of observations to return. Defaults to 60. required: false schema: type: integer format: int32 responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetBlsSeriesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-economic-calendar: get: tags: - EconomicService summary: GetEconomicCalendar description: GetEconomicCalendar retrieves upcoming major economic events (FOMC, CPI, NFP, etc). operationId: GetEconomicCalendar parameters: - name: fromDate in: query required: false schema: type: string - name: toDate in: query required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEconomicCalendarResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-crude-inventories: get: tags: - EconomicService summary: GetCrudeInventories description: GetCrudeInventories retrieves the 8 most recent weeks of US crude oil stockpile data from EIA (WCRSTUS1). operationId: GetCrudeInventories responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetCrudeInventoriesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-nat-gas-storage: get: tags: - EconomicService summary: GetNatGasStorage description: GetNatGasStorage retrieves the 8 most recent weeks of US natural gas working gas storage from EIA (NW2_EPG0_SWO_R48_BCF). operationId: GetNatGasStorage responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetNatGasStorageResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-ecb-fx-rates: get: tags: - EconomicService summary: GetEcbFxRates description: GetEcbFxRates retrieves daily ECB official reference rates for EUR/major currency pairs. operationId: GetEcbFxRates responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEcbFxRatesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-eurostat-country-data: get: tags: - EconomicService summary: GetEurostatCountryData description: GetEurostatCountryData retrieves per-country CPI, unemployment, and GDP growth for 10 EU member states. operationId: GetEurostatCountryData responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEurostatCountryDataResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-eu-gas-storage: get: tags: - EconomicService summary: GetEuGasStorage description: GetEuGasStorage retrieves EU aggregate natural gas storage fill % from GIE AGSI+. operationId: GetEuGasStorage responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEuGasStorageResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-eu-yield-curve: get: tags: - EconomicService summary: GetEuYieldCurve description: GetEuYieldCurve retrieves the ECB Euro Area AAA sovereign yield curve (Svensson model spot rates). operationId: GetEuYieldCurve responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEuYieldCurveResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-eu-fsi: get: tags: - EconomicService summary: GetEuFsi description: GetEuFsi retrieves the ECB CISS (Composite Indicator of Systemic Stress) for the Euro area. operationId: GetEuFsi responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEuFsiResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-economic-stress: get: tags: - EconomicService summary: GetEconomicStress description: GetEconomicStress retrieves the composite Economic Stress Index (0-100) from 6 FRED series. operationId: GetEconomicStress responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEconomicStressResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-fao-food-price-index: get: tags: - EconomicService summary: GetFaoFoodPriceIndex description: GetFaoFoodPriceIndex retrieves the FAO Food Price Index for the past 12 months. operationId: GetFaoFoodPriceIndex responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetFaoFoodPriceIndexResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-oil-stocks-analysis: get: tags: - EconomicService summary: GetOilStocksAnalysis description: GetOilStocksAnalysis retrieves the IEA oil stocks days-of-cover ranking and regional summary. operationId: GetOilStocksAnalysis responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetOilStocksAnalysisResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-oil-inventories: get: tags: - EconomicService summary: GetOilInventories operationId: GetOilInventories responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetOilInventoriesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/economic/v1/get-energy-crisis-policies: get: tags: - EconomicService summary: GetEnergyCrisisPolicies description: GetEnergyCrisisPolicies retrieves government policy responses to the 2026 energy crisis from the IEA tracker. operationId: GetEnergyCrisisPolicies parameters: - name: country_code in: query description: Optional ISO-2 country code filter. required: false schema: type: string - name: category in: query description: 'Optional category filter: "conservation" or "consumer_support".' required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetEnergyCrisisPoliciesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. GetFredSeriesRequest: type: object properties: seriesId: type: string minLength: 1 description: FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL"). limit: type: integer format: int32 description: Maximum number of observations to return. Defaults to 120. required: - seriesId description: GetFredSeriesRequest specifies which FRED series to retrieve. GetFredSeriesResponse: type: object properties: series: $ref: '#/components/schemas/FredSeries' description: GetFredSeriesResponse contains the requested FRED series data. FredSeries: type: object properties: seriesId: type: string minLength: 1 description: Series identifier (e.g., "GDP", "UNRATE", "CPIAUCSL"). title: type: string description: Series title. units: type: string description: Unit of measurement. frequency: type: string description: Data frequency (e.g., "Monthly", "Quarterly"). observations: type: array items: $ref: '#/components/schemas/FredObservation' required: - seriesId description: FredSeries represents a FRED time series with metadata. FredObservation: type: object properties: date: type: string description: Observation date as YYYY-MM-DD string. value: type: number format: double description: Observation value. description: FredObservation represents a single data point from a FRED economic series. ListWorldBankIndicatorsRequest: type: object properties: indicatorCode: type: string minLength: 1 description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD"). countryCode: type: string description: Optional country filter (ISO 3166-1 alpha-2). year: type: integer format: int32 description: Optional year filter. Defaults to latest available. pageSize: type: integer format: int32 description: Maximum items per page. cursor: type: string description: Cursor for next page. required: - indicatorCode description: ListWorldBankIndicatorsRequest specifies filters for retrieving World Bank data. ListWorldBankIndicatorsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/WorldBankCountryData' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListWorldBankIndicatorsResponse contains World Bank indicator data. WorldBankCountryData: type: object properties: countryCode: type: string minLength: 1 description: ISO 3166-1 alpha-2 country code. countryName: type: string description: Country name. indicatorCode: type: string minLength: 1 description: World Bank indicator code (e.g., "NY.GDP.MKTP.CD"). indicatorName: type: string description: Indicator name. year: type: integer format: int32 description: Data year. value: type: number format: double description: Indicator value. required: - countryCode - indicatorCode description: WorldBankCountryData represents a World Bank indicator value for a country. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results. GetEnergyPricesRequest: type: object properties: commodities: type: array items: type: string description: Optional commodity filter. Empty returns all tracked commodities. description: GetEnergyPricesRequest specifies which energy commodities to retrieve. GetEnergyPricesResponse: type: object properties: prices: type: array items: $ref: '#/components/schemas/EnergyPrice' description: GetEnergyPricesResponse contains energy price data. EnergyPrice: type: object properties: commodity: type: string minLength: 1 description: Energy commodity identifier. name: type: string description: Human-readable name (e.g., "WTI Crude Oil", "Henry Hub Natural Gas"). price: type: number format: double description: Current price in USD. unit: type: string description: Unit of measurement (e.g., "$/barrel", "$/MMBtu"). change: type: number format: double description: Percentage change from previous period. priceAt: type: integer format: int64 description: 'Price date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' required: - commodity description: EnergyPrice represents a current energy commodity price from EIA. GetMacroSignalsRequest: type: object description: GetMacroSignalsRequest requests the current macro signal dashboard. GetMacroSignalsResponse: type: object properties: timestamp: type: string description: ISO 8601 timestamp of computation. verdict: type: string description: 'Overall verdict: "BUY", "CASH", or "UNKNOWN".' bullishCount: type: integer format: int32 description: Number of bullish signals. totalCount: type: integer format: int32 description: Total number of evaluated signals (excluding UNKNOWN). signals: $ref: '#/components/schemas/MacroSignals' meta: $ref: '#/components/schemas/MacroMeta' unavailable: type: boolean description: True when upstream data is unavailable (fallback result). description: GetMacroSignalsResponse contains the full macro signal dashboard with 7 signals and verdict. MacroSignals: type: object properties: liquidity: $ref: '#/components/schemas/LiquiditySignal' flowStructure: $ref: '#/components/schemas/FlowStructureSignal' macroRegime: $ref: '#/components/schemas/MacroRegimeSignal' technicalTrend: $ref: '#/components/schemas/TechnicalTrendSignal' hashRate: $ref: '#/components/schemas/HashRateSignal' priceMomentum: $ref: '#/components/schemas/PriceMomentumSignal' fearGreed: $ref: '#/components/schemas/FearGreedSignal' description: MacroSignals contains all 7 individual signal computations. LiquiditySignal: type: object properties: status: type: string description: '"SQUEEZE", "NORMAL", or "UNKNOWN".' value: type: number format: double description: JPY 30d ROC percentage, absent if unavailable. sparkline: type: array items: type: number format: double description: Last 30 JPY close prices. description: LiquiditySignal tracks JPY 30d rate of change as a liquidity proxy. FlowStructureSignal: type: object properties: status: type: string description: '"PASSIVE GAP", "ALIGNED", or "UNKNOWN".' btcReturn5: type: number format: double description: BTC 5-day return percentage. qqqReturn5: type: number format: double description: QQQ 5-day return percentage. description: FlowStructureSignal compares BTC vs QQQ 5-day returns. MacroRegimeSignal: type: object properties: status: type: string description: '"RISK-ON", "DEFENSIVE", or "UNKNOWN".' qqqRoc20: type: number format: double description: QQQ 20d ROC percentage. xlpRoc20: type: number format: double description: XLP 20d ROC percentage. description: MacroRegimeSignal compares QQQ vs XLP 20-day rate of change. TechnicalTrendSignal: type: object properties: status: type: string description: '"BULLISH", "BEARISH", "NEUTRAL", or "UNKNOWN".' btcPrice: type: number format: double description: Current BTC price. sma50: type: number format: double description: 50-day simple moving average. sma200: type: number format: double description: 200-day simple moving average. vwap30d: type: number format: double description: 30-day volume-weighted average price. mayerMultiple: type: number format: double description: Mayer multiple (BTC price / SMA200). sparkline: type: array items: type: number format: double description: Last 30 BTC close prices. description: TechnicalTrendSignal evaluates BTC price vs moving averages and VWAP. HashRateSignal: type: object properties: status: type: string description: '"GROWING", "DECLINING", "STABLE", or "UNKNOWN".' change30d: type: number format: double description: Hash rate change over 30 days as percentage. description: HashRateSignal tracks Bitcoin hash rate momentum. PriceMomentumSignal: type: object properties: status: type: string description: '"STRONG", "MODERATE", "WEAK", or "UNKNOWN".' description: PriceMomentumSignal uses the Mayer Multiple (price/SMA200) as a market-adaptive signal. FearGreedSignal: type: object properties: status: type: string description: Classification label (e.g., "Extreme Fear", "Greed"). value: type: integer format: int32 description: Current index value (0-100). history: type: array items: $ref: '#/components/schemas/FearGreedHistoryEntry' description: FearGreedSignal tracks the Crypto Fear & Greed index. FearGreedHistoryEntry: type: object properties: value: type: integer maximum: 100 minimum: 0 format: int32 description: Index value (0-100). date: type: string description: Date string (YYYY-MM-DD). description: FearGreedHistoryEntry is a single day's Fear & Greed index reading. MacroMeta: type: object properties: qqqSparkline: type: array items: type: number format: double description: Last 30 QQQ close prices for sparkline. description: MacroMeta contains supplementary chart data. GetEnergyCapacityRequest: type: object properties: energySources: type: array items: type: string description: |- Energy source codes to query (e.g., "SUN", "WND", "COL"). Empty returns all tracked sources (SUN, WND, COL). years: type: integer format: int32 description: Number of years of historical data. Default 20 if not set. GetEnergyCapacityResponse: type: object properties: series: type: array items: $ref: '#/components/schemas/EnergyCapacitySeries' EnergyCapacitySeries: type: object properties: energySource: type: string name: type: string data: type: array items: $ref: '#/components/schemas/EnergyCapacityYear' EnergyCapacityYear: type: object properties: year: type: integer format: int32 capacityMw: type: number format: double GetBisPolicyRatesRequest: type: object description: GetBisPolicyRatesRequest requests central bank policy rates. GetBisPolicyRatesResponse: type: object properties: rates: type: array items: $ref: '#/components/schemas/BisPolicyRate' description: GetBisPolicyRatesResponse contains BIS policy rate data. BisPolicyRate: type: object properties: countryCode: type: string description: ISO 2-letter country code (US, GB, JP, etc.) countryName: type: string description: Country or region name. rate: type: number format: double description: Current policy rate percentage. previousRate: type: number format: double description: Previous period rate percentage. date: type: string description: Date as YYYY-MM. centralBank: type: string description: Central bank name (e.g. "Federal Reserve"). description: BisPolicyRate represents a central bank policy rate from BIS. GetBisExchangeRatesRequest: type: object description: GetBisExchangeRatesRequest requests effective exchange rates. GetBisExchangeRatesResponse: type: object properties: rates: type: array items: $ref: '#/components/schemas/BisExchangeRate' description: GetBisExchangeRatesResponse contains BIS effective exchange rate data. BisExchangeRate: type: object properties: countryCode: type: string description: ISO 2-letter country code. countryName: type: string description: Country or region name. realEer: type: number format: double description: Real effective exchange rate index. nominalEer: type: number format: double description: Nominal effective exchange rate index. realChange: type: number format: double description: Percentage change from previous period (real). date: type: string description: Date as YYYY-MM. description: BisExchangeRate represents effective exchange rate indices from BIS. GetBisCreditRequest: type: object description: GetBisCreditRequest requests credit-to-GDP ratio data. GetBisCreditResponse: type: object properties: entries: type: array items: $ref: '#/components/schemas/BisCreditToGdp' description: GetBisCreditResponse contains BIS credit-to-GDP data. BisCreditToGdp: type: object properties: countryCode: type: string description: ISO 2-letter country code. countryName: type: string description: Country or region name. creditGdpRatio: type: number format: double description: Total credit as percentage of GDP. previousRatio: type: number format: double description: Previous quarter ratio. date: type: string description: Date as YYYY-QN. description: BisCreditToGdp represents total credit as percentage of GDP from BIS. GetFredSeriesBatchRequest: type: object properties: seriesIds: type: array items: type: string maxItems: 10 minItems: 1 description: FRED series IDs (e.g., "WALCL", "FEDFUNDS"). Max 10. maxItems: 10 minItems: 1 limit: type: integer format: int32 description: Maximum number of observations per series. Defaults to 120. description: GetFredSeriesBatchRequest looks up multiple FRED series in a single call. GetFredSeriesBatchResponse: type: object properties: results: type: object additionalProperties: $ref: '#/components/schemas/FredSeries' description: Map of series_id -> FRED series for found series. fetched: type: integer format: int32 description: Number of series successfully fetched. requested: type: integer format: int32 description: Number of series requested. description: GetFredSeriesBatchResponse contains the requested FRED series data. ResultsEntry: type: object properties: key: type: string value: $ref: '#/components/schemas/FredSeries' ListGroceryBasketPricesRequest: type: object ListGroceryBasketPricesResponse: type: object properties: countries: type: array items: $ref: '#/components/schemas/CountryBasket' fetchedAt: type: string cheapestCountry: type: string mostExpensiveCountry: type: string upstreamUnavailable: type: boolean wowAvgPct: type: number format: double wowAvailable: type: boolean prevFetchedAt: type: string CountryBasket: type: object properties: code: type: string name: type: string currency: type: string flag: type: string totalUsd: type: number format: double fxRate: type: number format: double items: type: array items: $ref: '#/components/schemas/GroceryItemPrice' wowPct: type: number format: double GroceryItemPrice: type: object properties: itemId: type: string itemName: type: string unit: type: string localPrice: type: number format: double usdPrice: type: number format: double currency: type: string sourceSite: type: string available: type: boolean ListBigMacPricesRequest: type: object ListBigMacPricesResponse: type: object properties: countries: type: array items: $ref: '#/components/schemas/BigMacCountryPrice' fetchedAt: type: string cheapestCountry: type: string mostExpensiveCountry: type: string wowAvgPct: type: number format: double wowAvailable: type: boolean prevFetchedAt: type: string BigMacCountryPrice: type: object properties: code: type: string name: type: string currency: type: string flag: type: string localPrice: type: number format: double usdPrice: type: number format: double fxRate: type: number format: double sourceSite: type: string available: type: boolean wowPct: type: number format: double GetNationalDebtRequest: type: object description: GetNationalDebtRequest requests national debt data for all countries. GetNationalDebtResponse: type: object properties: entries: type: array items: $ref: '#/components/schemas/NationalDebtEntry' seededAt: type: string description: ISO 8601 timestamp when seed data was written. unavailable: type: boolean description: True when upstream data is unavailable (fallback result). description: GetNationalDebtResponse wraps the full list of national debt entries. NationalDebtEntry: type: object properties: iso3: type: string description: ISO3 country code (e.g. "USA"). debtUsd: type: number format: double description: Total debt in USD at baseline_ts. gdpUsd: type: number format: double description: GDP in USD (nominal, latest year). debtToGdp: type: number format: double description: Debt as % of GDP. annualGrowth: type: number format: double description: Year-over-year debt growth percent (2023->2024). perSecondRate: type: number format: double description: Deficit-derived accrual in USD per second. perDayRate: type: number format: double description: Deficit-derived accrual in USD per day. baselineTs: type: string format: int64 description: UTC ms timestamp anchoring the debt_usd figure (2024-01-01T00:00:00Z). source: type: string description: Human-readable source string. description: NationalDebtEntry holds debt data for a single country. ListFuelPricesRequest: type: object ListFuelPricesResponse: type: object properties: countries: type: array items: $ref: '#/components/schemas/FuelCountryPrice' fetchedAt: type: string cheapestGasoline: type: string cheapestDiesel: type: string mostExpensiveGasoline: type: string mostExpensiveDiesel: type: string wowAvailable: type: boolean prevFetchedAt: type: string sourceCount: type: integer format: int32 countryCount: type: integer format: int32 FuelCountryPrice: type: object properties: code: type: string name: type: string currency: type: string flag: type: string gasoline: $ref: '#/components/schemas/FuelPrice' diesel: $ref: '#/components/schemas/FuelPrice' fxRate: type: number format: double FuelPrice: type: object properties: usdPrice: type: number format: double localPrice: type: number format: double grade: type: string source: type: string available: type: boolean wowPct: type: number format: double observedAt: type: string GetBlsSeriesRequest: type: object properties: seriesId: type: string description: BLS series ID (e.g. "CES0500000001", "CIU1010000000000A"). limit: type: integer format: int32 description: Maximum number of observations to return. Defaults to 60. description: GetBlsSeriesRequest specifies which BLS series to retrieve. GetBlsSeriesResponse: type: object properties: series: $ref: '#/components/schemas/BlsSeries' description: GetBlsSeriesResponse contains the requested BLS series data. BlsSeries: type: object properties: seriesId: type: string description: BLS series ID (e.g. "CES0500000001"). title: type: string description: Human-readable series title. units: type: string description: Unit of measure. observations: type: array items: $ref: '#/components/schemas/BlsObservation' description: BlsSeries is a BLS time series with metadata and observations. BlsObservation: type: object properties: year: type: string description: Year of the observation. period: type: string description: Period code (e.g. "M01" for January, "A01" for annual). periodName: type: string description: Human-readable period name. value: type: string description: Observed value. description: BlsObservation is a single BLS data point. GetEconomicCalendarRequest: type: object properties: fromDate: type: string toDate: type: string GetEconomicCalendarResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/EconomicEvent' fromDate: type: string toDate: type: string total: type: integer format: int32 unavailable: type: boolean EconomicEvent: type: object properties: event: type: string country: type: string date: type: string impact: type: string actual: type: string estimate: type: string previous: type: string unit: type: string GetCrudeInventoriesRequest: type: object description: GetCrudeInventoriesRequest is the request message for GetCrudeInventories. GetCrudeInventoriesResponse: type: object properties: weeks: type: array items: $ref: '#/components/schemas/CrudeInventoryWeek' latestPeriod: type: string description: Timestamp of the most recent EIA data point (ISO 8601). description: GetCrudeInventoriesResponse contains the 8 most recent weeks of US crude oil inventory data. CrudeInventoryWeek: type: object properties: period: type: string description: ISO week period (YYYY-MM-DD, Monday of the EIA report week). stocksMb: type: number format: double description: Total crude oil stocks in millions of barrels. weeklyChangeMb: type: number format: double description: |- Week-over-week change in millions of barrels. Positive = build (bearish), negative = draw (bullish). Absent for the oldest week when no prior week is available for comparison. description: CrudeInventoryWeek represents one week of US crude oil stockpile data from EIA WCRSTUS1. GetNatGasStorageRequest: type: object description: GetNatGasStorageRequest is the request message for GetNatGasStorage. GetNatGasStorageResponse: type: object properties: weeks: type: array items: $ref: '#/components/schemas/NatGasStorageWeek' latestPeriod: type: string description: Timestamp of the most recent EIA data point (ISO 8601). description: GetNatGasStorageResponse contains the 8 most recent weeks of US natural gas storage data. NatGasStorageWeek: type: object properties: period: type: string description: ISO week period (YYYY-MM-DD, Monday of the EIA report week). storBcf: type: number format: double description: Working gas in underground storage, Lower-48 States, in Bcf. weeklyChangeBcf: type: number format: double description: |- Week-over-week change in Bcf. Positive = build (bearish for gas prices), negative = draw (bullish). Absent for the oldest week when no prior week is available for comparison. description: NatGasStorageWeek represents one week of US natural gas working gas storage data from EIA. GetEcbFxRatesRequest: type: object description: GetEcbFxRatesRequest is empty; returns all tracked EUR pairs. GetEcbFxRatesResponse: type: object properties: rates: type: array items: $ref: '#/components/schemas/EcbFxRate' updatedAt: type: string description: ISO 8601 timestamp of the ECB publication. seededAt: type: string format: int64 description: Unix ms when the data was last seeded. unavailable: type: boolean description: True when Redis key is missing or data is unavailable. description: GetEcbFxRatesResponse contains the latest ECB reference rates. EcbFxRate: type: object properties: pair: type: string description: Currency pair label, e.g. "EURUSD". rate: type: number format: double description: Exchange rate (units of quote currency per 1 EUR). date: type: string description: Date of the observation in YYYY-MM-DD format. change1d: type: number format: double description: 1-day change in rate (absolute). description: EcbFxRate is a single ECB official reference rate for a currency pair. GetEurostatCountryDataRequest: type: object description: GetEurostatCountryDataRequest requests Eurostat per-country economic data. GetEurostatCountryDataResponse: type: object properties: countries: type: object additionalProperties: $ref: '#/components/schemas/EurostatCountryEntry' description: Map of ISO2 country code to economic metrics (e.g. "DE", "FR", "IT"). seededAt: type: string format: int64 description: UTC ms timestamp when seed data was written. unavailable: type: boolean description: True when upstream data is unavailable (fallback result). description: GetEurostatCountryDataResponse contains per-country CPI, unemployment, and GDP growth. CountriesEntry: type: object properties: key: type: string value: $ref: '#/components/schemas/EurostatCountryEntry' EurostatCountryEntry: type: object properties: cpi: $ref: '#/components/schemas/EurostatMetric' unemployment: $ref: '#/components/schemas/EurostatMetric' gdpGrowth: $ref: '#/components/schemas/EurostatMetric' description: EurostatCountryEntry holds all available metrics for one EU country. EurostatMetric: type: object properties: value: type: number format: double description: Numeric value (e.g. 2.3 for 2.3%). date: type: string description: Period string (e.g. "2024-01" for monthly, "2024-Q1" for quarterly). unit: type: string description: Unit of measurement (e.g. "%"). priorValue: type: number format: double description: Prior period value for delta calculation (e.g. previous month/quarter). hasPrior: type: boolean description: True when prior_value is present (proto3 can't distinguish 0 from absent). description: EurostatMetric holds a single economic metric value for a country. GetEuGasStorageRequest: type: object description: GetEuGasStorageRequest is empty — returns latest EU aggregate snapshot. GetEuGasStorageResponse: type: object properties: fillPct: type: number format: double description: Current storage fill level as a percentage of working gas volume (0–100). fillPctChange1d: type: number format: double description: 1-day change in fill percentage (positive = injecting, negative = withdrawing). gasDaysConsumption: type: number format: double description: Approximate days of consumption remaining at average EU winter drawdown rate. trend: type: string description: 'Current storage trend: "injecting", "withdrawing", or "stable".' history: type: array items: $ref: '#/components/schemas/EuGasStorageHistoryEntry' seededAt: type: string format: int64 description: UTC ms timestamp when seed data was written. updatedAt: type: string description: Calendar date of the most recent data point (YYYY-MM-DD). unavailable: type: boolean description: True when upstream data is unavailable (fallback result). description: GetEuGasStorageResponse contains the EU aggregate gas storage snapshot. EuGasStorageHistoryEntry: type: object properties: date: type: string description: Calendar date (YYYY-MM-DD). fillPct: type: number format: double description: Storage fill level as a percentage of working gas volume capacity. gasTwh: type: number format: double description: Working gas volume in storage (TWh). description: EuGasStorageHistoryEntry represents one day of EU aggregate gas storage data. GetEuYieldCurveRequest: type: object description: GetEuYieldCurveRequest fetches the ECB Euro Area AAA sovereign yield curve. GetEuYieldCurveResponse: type: object properties: data: $ref: '#/components/schemas/EuYieldCurveData' unavailable: type: boolean description: True if data is not yet available in cache. description: GetEuYieldCurveResponse contains the latest ECB Euro Area AAA sovereign yield curve. EuYieldCurveData: type: object properties: date: type: string description: Date of the observation (YYYY-MM or YYYY-MM-DD). rates: type: object additionalProperties: type: number format: double description: 'Spot rates by tenor. Keys: "1Y", "2Y", "5Y", "10Y", "20Y", "30Y".' source: type: string description: Data source identifier (e.g. "ecb-aaa"). updatedAt: type: string description: ISO 8601 timestamp when this was last seeded. description: EuYieldCurveData holds a single observation of the ECB Euro Area AAA yield curve. RatesEntry: type: object properties: key: type: string value: type: number format: double GetEuFsiRequest: type: object GetEuFsiResponse: type: object properties: latestValue: type: number format: double latestDate: type: string label: type: string history: type: array items: $ref: '#/components/schemas/EuFsiObservation' seededAt: type: string unavailable: type: boolean EuFsiObservation: type: object properties: date: type: string value: type: number format: double GetEconomicStressRequest: type: object GetEconomicStressResponse: type: object properties: compositeScore: type: number format: double label: type: string components: type: array items: $ref: '#/components/schemas/EconomicStressComponent' seededAt: type: string unavailable: type: boolean EconomicStressComponent: type: object properties: id: type: string label: type: string rawValue: type: number format: double score: type: number format: double weight: type: number format: double missing: type: boolean GetFaoFoodPriceIndexRequest: type: object GetFaoFoodPriceIndexResponse: type: object properties: points: type: array items: $ref: '#/components/schemas/FaoFoodPricePoint' fetchedAt: type: string currentFfpi: type: number format: double momPct: type: number format: double yoyPct: type: number format: double FaoFoodPricePoint: type: object properties: date: type: string ffpi: type: number format: double meat: type: number format: double dairy: type: number format: double cereals: type: number format: double oils: type: number format: double sugar: type: number format: double GetOilStocksAnalysisRequest: type: object description: GetOilStocksAnalysisRequest is empty — returns the latest global analysis snapshot. GetOilStocksAnalysisResponse: type: object properties: updatedAt: type: string description: UTC ISO-8601 timestamp when this analysis was written. dataMonth: type: string description: 'Data month in YYYY-MM format (source: IEA monthly release).' ieaMembers: type: array items: $ref: '#/components/schemas/OilStocksAnalysisMember' belowObligation: type: array items: type: string description: ISO2 codes of countries currently below the 90-day obligation. regionalSummary: $ref: '#/components/schemas/OilStocksRegionalSummary' unavailable: type: boolean description: True when upstream seed data is unavailable (fallback result). description: GetOilStocksAnalysisResponse contains the IEA oil stocks days-of-cover analysis. OilStocksAnalysisMember: type: object properties: iso2: type: string description: ISO 3166-1 alpha-2 country code. daysOfCover: type: integer format: int32 description: Days of supply cover (absent when country is a net exporter or data anomaly). netExporter: type: boolean description: True when the country is classified as a net exporter by IEA. belowObligation: type: boolean description: True when days_of_cover < 90 (IEA 90-day obligation threshold). obligationMet: type: boolean description: True when the 90-day obligation is met (net exporters always true). rank: type: integer format: int32 description: Rank within the IEA member ranking (1-indexed, net exporters ranked last). vsObligation: type: integer format: int32 description: days_of_cover - 90; absent for net exporters. description: OilStocksAnalysisMember holds days-of-cover data and obligation status for one IEA member country. OilStocksRegionalSummary: type: object properties: europe: $ref: '#/components/schemas/OilStocksRegionalSummaryEurope' asiaPacific: $ref: '#/components/schemas/OilStocksRegionalSummaryAsiaPacific' northAmerica: $ref: '#/components/schemas/OilStocksRegionalSummaryNorthAmerica' description: OilStocksRegionalSummary holds regional aggregates for the three IEA regions. OilStocksRegionalSummaryEurope: type: object properties: avgDays: type: integer format: int32 description: Mean days of cover across non-net-exporter European members. minDays: type: integer format: int32 description: Minimum days of cover across non-net-exporter European members. countBelowObligation: type: integer format: int32 description: Count of European members below the 90-day obligation. description: OilStocksRegionalSummaryEurope aggregates days-of-cover for European IEA members. OilStocksRegionalSummaryAsiaPacific: type: object properties: avgDays: type: integer format: int32 description: Mean days of cover across Asia-Pacific members (AU, JP, KR, NZ). minDays: type: integer format: int32 description: Minimum days of cover across Asia-Pacific members. countBelowObligation: type: integer format: int32 description: Count of Asia-Pacific members below the 90-day obligation. description: OilStocksRegionalSummaryAsiaPacific aggregates days-of-cover for Asia-Pacific IEA members. OilStocksRegionalSummaryNorthAmerica: type: object properties: netExporters: type: integer format: int32 description: Count of net exporters in North America (CA, MX, US). avgDays: type: integer format: int32 description: Average days of cover for non-exporter North American members (if any). description: OilStocksRegionalSummaryNorthAmerica aggregates data for North American IEA members. GetOilInventoriesRequest: type: object GetOilInventoriesResponse: type: object properties: crudeWeeks: type: array items: $ref: '#/components/schemas/CrudeInventoryWeekRef' spr: $ref: '#/components/schemas/OilInventoriesSprSnapshot' natGasWeeks: type: array items: $ref: '#/components/schemas/NatGasWeekRef' euGas: $ref: '#/components/schemas/OilInventoriesEuGas' ieaStocks: $ref: '#/components/schemas/OilInventoriesIeaStocks' refinery: $ref: '#/components/schemas/OilInventoriesRefinery' updatedAt: type: string CrudeInventoryWeekRef: type: object properties: period: type: string stocksMb: type: number format: double weeklyChangeMb: type: number format: double OilInventoriesSprSnapshot: type: object properties: latestStocksMb: type: number format: double changeWow: type: number format: double weeks: type: array items: $ref: '#/components/schemas/OilInventoriesSprWeek' OilInventoriesSprWeek: type: object properties: period: type: string stocksMb: type: number format: double NatGasWeekRef: type: object properties: period: type: string storBcf: type: number format: double weeklyChangeBcf: type: number format: double OilInventoriesEuGas: type: object properties: fillPct: type: number format: double fillPctChange1d: type: number format: double trend: type: string history: type: array items: $ref: '#/components/schemas/OilInventoriesEuGasDay' OilInventoriesEuGasDay: type: object properties: date: type: string fillPct: type: number format: double OilInventoriesIeaStocks: type: object properties: dataMonth: type: string members: type: array items: $ref: '#/components/schemas/OilInventoriesIeaMember' europe: $ref: '#/components/schemas/OilInventoriesRegionStats' asiaPacific: $ref: '#/components/schemas/OilInventoriesRegionStats' northAmerica: $ref: '#/components/schemas/OilInventoriesRegionStats' OilInventoriesIeaMember: type: object properties: iso2: type: string daysOfCover: type: number format: double netExporter: type: boolean belowObligation: type: boolean OilInventoriesRegionStats: type: object properties: avgDays: type: number format: double minDays: type: number format: double countBelowObligation: type: integer format: int32 OilInventoriesRefinery: type: object properties: inputsMbpd: type: number format: double period: type: string GetEnergyCrisisPoliciesRequest: type: object properties: countryCode: type: string description: Optional ISO-2 country code filter. category: type: string description: 'Optional category filter: "conservation" or "consumer_support".' description: GetEnergyCrisisPoliciesRequest allows optional filtering by country or category. GetEnergyCrisisPoliciesResponse: type: object properties: source: type: string description: Source attribution. sourceUrl: type: string description: Source URL. context: type: string description: Context description. policies: type: array items: $ref: '#/components/schemas/EnergyCrisisPolicy' updatedAt: type: string description: UTC ISO-8601 timestamp when this data was last updated. unavailable: type: boolean description: True when upstream seed data is unavailable (fallback result). description: GetEnergyCrisisPoliciesResponse contains energy crisis policy data from the IEA tracker. EnergyCrisisPolicy: type: object properties: country: type: string description: Country name. countryCode: type: string description: ISO 3166-1 alpha-2 country code. category: type: string description: 'Policy category: "conservation" or "consumer_support".' sector: type: string description: 'Affected sector: transport, buildings, industry, electricity, agriculture, general.' measure: type: string description: Description of the policy measure. dateAnnounced: type: string description: Date announced in ISO-8601 (YYYY-MM-DD) format. status: type: string description: 'Status of the policy: active, planned, or ended.' description: EnergyCrisisPolicy represents a single government policy response to the 2026 energy crisis.