EconomicService.openapi.yaml

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'
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