{ "components": { "schemas": { "BisCreditToGdp": { "description": "BisCreditToGdp represents total credit as percentage of GDP from BIS.", "properties": { "countryCode": { "description": "ISO 2-letter country code.", "type": "string" }, "countryName": { "description": "Country or region name.", "type": "string" }, "creditGdpRatio": { "description": "Total credit as percentage of GDP.", "format": "double", "type": "number" }, "date": { "description": "Date as YYYY-QN.", "type": "string" }, "previousRatio": { "description": "Previous quarter ratio.", "format": "double", "type": "number" } }, "type": "object" }, "BisExchangeRate": { "description": "BisExchangeRate represents effective exchange rate indices from BIS.", "properties": { "countryCode": { "description": "ISO 2-letter country code.", "type": "string" }, "countryName": { "description": "Country or region name.", "type": "string" }, "date": { "description": "Date as YYYY-MM.", "type": "string" }, "nominalEer": { "description": "Nominal effective exchange rate index.", "format": "double", "type": "number" }, "realChange": { "description": "Percentage change from previous period (real).", "format": "double", "type": "number" }, "realEer": { "description": "Real effective exchange rate index.", "format": "double", "type": "number" } }, "type": "object" }, "BisPolicyRate": { "description": "BisPolicyRate represents a central bank policy rate from BIS.", "properties": { "centralBank": { "description": "Central bank name (e.g. \"Federal Reserve\").", "type": "string" }, "countryCode": { "description": "ISO 2-letter country code (US, GB, JP, etc.)", "type": "string" }, "countryName": { "description": "Country or region name.", "type": "string" }, "date": { "description": "Date as YYYY-MM.", "type": "string" }, "previousRate": { "description": "Previous period rate percentage.", "format": "double", "type": "number" }, "rate": { "description": "Current policy rate percentage.", "format": "double", "type": "number" } }, "type": "object" }, "EnergyCapacitySeries": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EnergyCapacityYear" }, "type": "array" }, "energySource": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "EnergyCapacityYear": { "properties": { "capacityMw": { "format": "double", "type": "number" }, "year": { "format": "int32", "type": "integer" } }, "type": "object" }, "EnergyPrice": { "description": "EnergyPrice represents a current energy commodity price from EIA.", "properties": { "change": { "description": "Percentage change from previous period.", "format": "double", "type": "number" }, "commodity": { "description": "Energy commodity identifier.", "minLength": 1, "type": "string" }, "name": { "description": "Human-readable name (e.g., \"WTI Crude Oil\", \"Henry Hub Natural Gas\").", "type": "string" }, "price": { "description": "Current price in USD.", "format": "double", "type": "number" }, "priceAt": { "description": "Price date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript", "format": "int64", "type": "integer" }, "unit": { "description": "Unit of measurement (e.g., \"$/barrel\", \"$/MMBtu\").", "type": "string" } }, "required": [ "commodity" ], "type": "object" }, "Error": { "description": "Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.", "properties": { "message": { "description": "Error message (e.g., 'user not found', 'database connection failed')", "type": "string" } }, "type": "object" }, "FearGreedHistoryEntry": { "description": "FearGreedHistoryEntry is a single day's Fear & Greed index reading.", "properties": { "date": { "description": "Date string (YYYY-MM-DD).", "type": "string" }, "value": { "description": "Index value (0-100).", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" } }, "type": "object" }, "FearGreedSignal": { "description": "FearGreedSignal tracks the Crypto Fear & Greed index.", "properties": { "history": { "items": { "$ref": "#/components/schemas/FearGreedHistoryEntry" }, "type": "array" }, "status": { "description": "Classification label (e.g., \"Extreme Fear\", \"Greed\").", "type": "string" }, "value": { "description": "Current index value (0-100).", "format": "int32", "type": "integer" } }, "type": "object" }, "FieldViolation": { "description": "FieldViolation describes a single validation error for a specific field.", "properties": { "description": { "description": "Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')", "type": "string" }, "field": { "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')", "type": "string" } }, "required": [ "field", "description" ], "type": "object" }, "FlowStructureSignal": { "description": "FlowStructureSignal compares BTC vs QQQ 5-day returns.", "properties": { "btcReturn5": { "description": "BTC 5-day return percentage.", "format": "double", "type": "number" }, "qqqReturn5": { "description": "QQQ 5-day return percentage.", "format": "double", "type": "number" }, "status": { "description": "\"PASSIVE GAP\", \"ALIGNED\", or \"UNKNOWN\".", "type": "string" } }, "type": "object" }, "FredObservation": { "description": "FredObservation represents a single data point from a FRED economic series.", "properties": { "date": { "description": "Observation date as YYYY-MM-DD string.", "type": "string" }, "value": { "description": "Observation value.", "format": "double", "type": "number" } }, "type": "object" }, "FredSeries": { "description": "FredSeries represents a FRED time series with metadata.", "properties": { "frequency": { "description": "Data frequency (e.g., \"Monthly\", \"Quarterly\").", "type": "string" }, "observations": { "items": { "$ref": "#/components/schemas/FredObservation" }, "type": "array" }, "seriesId": { "description": "Series identifier (e.g., \"GDP\", \"UNRATE\", \"CPIAUCSL\").", "minLength": 1, "type": "string" }, "title": { "description": "Series title.", "type": "string" }, "units": { "description": "Unit of measurement.", "type": "string" } }, "required": [ "seriesId" ], "type": "object" }, "GetBisCreditRequest": { "description": "GetBisCreditRequest requests credit-to-GDP ratio data.", "type": "object" }, "GetBisCreditResponse": { "description": "GetBisCreditResponse contains BIS credit-to-GDP data.", "properties": { "entries": { "items": { "$ref": "#/components/schemas/BisCreditToGdp" }, "type": "array" } }, "type": "object" }, "GetBisExchangeRatesRequest": { "description": "GetBisExchangeRatesRequest requests effective exchange rates.", "type": "object" }, "GetBisExchangeRatesResponse": { "description": "GetBisExchangeRatesResponse contains BIS effective exchange rate data.", "properties": { "rates": { "items": { "$ref": "#/components/schemas/BisExchangeRate" }, "type": "array" } }, "type": "object" }, "GetBisPolicyRatesRequest": { "description": "GetBisPolicyRatesRequest requests central bank policy rates.", "type": "object" }, "GetBisPolicyRatesResponse": { "description": "GetBisPolicyRatesResponse contains BIS policy rate data.", "properties": { "rates": { "items": { "$ref": "#/components/schemas/BisPolicyRate" }, "type": "array" } }, "type": "object" }, "GetEnergyCapacityRequest": { "properties": { "energySources": { "items": { "description": "Energy source codes to query (e.g., \"SUN\", \"WND\", \"COL\").\n Empty returns all tracked sources (SUN, WND, COL).", "type": "string" }, "type": "array" }, "years": { "description": "Number of years of historical data. Default 20 if not set.", "format": "int32", "type": "integer" } }, "type": "object" }, "GetEnergyCapacityResponse": { "properties": { "series": { "items": { "$ref": "#/components/schemas/EnergyCapacitySeries" }, "type": "array" } }, "type": "object" }, "GetEnergyPricesRequest": { "description": "GetEnergyPricesRequest specifies which energy commodities to retrieve.", "properties": { "commodities": { "items": { "description": "Optional commodity filter. Empty returns all tracked commodities.", "type": "string" }, "type": "array" } }, "type": "object" }, "GetEnergyPricesResponse": { "description": "GetEnergyPricesResponse contains energy price data.", "properties": { "prices": { "items": { "$ref": "#/components/schemas/EnergyPrice" }, "type": "array" } }, "type": "object" }, "GetFredSeriesRequest": { "description": "GetFredSeriesRequest specifies which FRED series to retrieve.", "properties": { "limit": { "description": "Maximum number of observations to return. Defaults to 120.", "format": "int32", "type": "integer" }, "seriesId": { "description": "FRED series ID (e.g., \"GDP\", \"UNRATE\", \"CPIAUCSL\").", "minLength": 1, "type": "string" } }, "required": [ "seriesId" ], "type": "object" }, "GetFredSeriesResponse": { "description": "GetFredSeriesResponse contains the requested FRED series data.", "properties": { "series": { "$ref": "#/components/schemas/FredSeries" } }, "type": "object" }, "GetMacroSignalsRequest": { "description": "GetMacroSignalsRequest requests the current macro signal dashboard.", "type": "object" }, "GetMacroSignalsResponse": { "description": "GetMacroSignalsResponse contains the full macro signal dashboard with 7 signals and verdict.", "properties": { "bullishCount": { "description": "Number of bullish signals.", "format": "int32", "type": "integer" }, "meta": { "$ref": "#/components/schemas/MacroMeta" }, "signals": { "$ref": "#/components/schemas/MacroSignals" }, "timestamp": { "description": "ISO 8601 timestamp of computation.", "type": "string" }, "totalCount": { "description": "Total number of evaluated signals (excluding UNKNOWN).", "format": "int32", "type": "integer" }, "unavailable": { "description": "True when upstream data is unavailable (fallback result).", "type": "boolean" }, "verdict": { "description": "Overall verdict: \"BUY\", \"CASH\", or \"UNKNOWN\".", "type": "string" } }, "type": "object" }, "HashRateSignal": { "description": "HashRateSignal tracks Bitcoin hash rate momentum.", "properties": { "change30d": { "description": "Hash rate change over 30 days as percentage.", "format": "double", "type": "number" }, "status": { "description": "\"GROWING\", \"DECLINING\", \"STABLE\", or \"UNKNOWN\".", "type": "string" } }, "type": "object" }, "LiquiditySignal": { "description": "LiquiditySignal tracks JPY 30d rate of change as a liquidity proxy.", "properties": { "sparkline": { "items": { "description": "Last 30 JPY close prices.", "format": "double", "type": "number" }, "type": "array" }, "status": { "description": "\"SQUEEZE\", \"NORMAL\", or \"UNKNOWN\".", "type": "string" }, "value": { "description": "JPY 30d ROC percentage, absent if unavailable.", "format": "double", "type": "number" } }, "type": "object" }, "ListWorldBankIndicatorsRequest": { "description": "ListWorldBankIndicatorsRequest specifies filters for retrieving World Bank data.", "properties": { "countryCode": { "description": "Optional country filter (ISO 3166-1 alpha-2).", "type": "string" }, "cursor": { "description": "Cursor for next page.", "type": "string" }, "indicatorCode": { "description": "World Bank indicator code (e.g., \"NY.GDP.MKTP.CD\").", "minLength": 1, "type": "string" }, "pageSize": { "description": "Maximum items per page.", "format": "int32", "type": "integer" }, "year": { "description": "Optional year filter. Defaults to latest available.", "format": "int32", "type": "integer" } }, "required": [ "indicatorCode" ], "type": "object" }, "ListWorldBankIndicatorsResponse": { "description": "ListWorldBankIndicatorsResponse contains World Bank indicator data.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WorldBankCountryData" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationResponse" } }, "type": "object" }, "MacroMeta": { "description": "MacroMeta contains supplementary chart data.", "properties": { "qqqSparkline": { "items": { "description": "Last 30 QQQ close prices for sparkline.", "format": "double", "type": "number" }, "type": "array" } }, "type": "object" }, "MacroRegimeSignal": { "description": "MacroRegimeSignal compares QQQ vs XLP 20-day rate of change.", "properties": { "qqqRoc20": { "description": "QQQ 20d ROC percentage.", "format": "double", "type": "number" }, "status": { "description": "\"RISK-ON\", \"DEFENSIVE\", or \"UNKNOWN\".", "type": "string" }, "xlpRoc20": { "description": "XLP 20d ROC percentage.", "format": "double", "type": "number" } }, "type": "object" }, "MacroSignals": { "description": "MacroSignals contains all 7 individual signal computations.", "properties": { "fearGreed": { "$ref": "#/components/schemas/FearGreedSignal" }, "flowStructure": { "$ref": "#/components/schemas/FlowStructureSignal" }, "hashRate": { "$ref": "#/components/schemas/HashRateSignal" }, "liquidity": { "$ref": "#/components/schemas/LiquiditySignal" }, "macroRegime": { "$ref": "#/components/schemas/MacroRegimeSignal" }, "technicalTrend": { "$ref": "#/components/schemas/TechnicalTrendSignal" }, "priceMomentum": { "$ref": "#/components/schemas/PriceMomentumSignal" } }, "type": "object" }, "PaginationResponse": { "description": "PaginationResponse contains pagination metadata returned alongside list results.", "properties": { "nextCursor": { "description": "Cursor for fetching the next page. Empty string indicates no more pages.", "type": "string" }, "totalCount": { "description": "Total count of items matching the query, if known. Zero if the total is unknown.", "format": "int32", "type": "integer" } }, "type": "object" }, "TechnicalTrendSignal": { "description": "TechnicalTrendSignal evaluates BTC price vs moving averages and VWAP.", "properties": { "btcPrice": { "description": "Current BTC price.", "format": "double", "type": "number" }, "mayerMultiple": { "description": "Mayer multiple (BTC price / SMA200).", "format": "double", "type": "number" }, "sma200": { "description": "200-day simple moving average.", "format": "double", "type": "number" }, "sma50": { "description": "50-day simple moving average.", "format": "double", "type": "number" }, "sparkline": { "items": { "description": "Last 30 BTC close prices.", "format": "double", "type": "number" }, "type": "array" }, "status": { "description": "\"BULLISH\", \"BEARISH\", \"NEUTRAL\", or \"UNKNOWN\".", "type": "string" }, "vwap30d": { "description": "30-day volume-weighted average price.", "format": "double", "type": "number" } }, "type": "object" }, "ValidationError": { "description": "ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.", "properties": { "violations": { "description": "List of validation violations", "items": { "$ref": "#/components/schemas/FieldViolation" }, "type": "array" } }, "required": [ "violations" ], "type": "object" }, "WorldBankCountryData": { "description": "WorldBankCountryData represents a World Bank indicator value for a country.", "properties": { "countryCode": { "description": "ISO 3166-1 alpha-2 country code.", "minLength": 1, "type": "string" }, "countryName": { "description": "Country name.", "type": "string" }, "indicatorCode": { "description": "World Bank indicator code (e.g., \"NY.GDP.MKTP.CD\").", "minLength": 1, "type": "string" }, "indicatorName": { "description": "Indicator name.", "type": "string" }, "value": { "description": "Indicator value.", "format": "double", "type": "number" }, "year": { "description": "Data year.", "format": "int32", "type": "integer" } }, "required": [ "countryCode", "indicatorCode" ], "type": "object" }, "PriceMomentumSignal": { "description": "PriceMomentumSignal uses the Mayer Multiple (price/SMA200) as a market-adaptive signal.", "properties": { "status": { "description": "\"STRONG\", \"MODERATE\", \"WEAK\", or \"UNKNOWN\".", "type": "string" } }, "type": "object" } } }, "info": { "title": "EconomicService API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/economic/v1/get-bis-credit": { "get": { "description": "GetBisCredit retrieves credit-to-GDP ratio data from BIS.", "operationId": "GetBisCredit", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBisCreditResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetBisCredit", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-bis-exchange-rates": { "get": { "description": "GetBisExchangeRates retrieves effective exchange rates from BIS.", "operationId": "GetBisExchangeRates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBisExchangeRatesResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetBisExchangeRates", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-bis-policy-rates": { "get": { "description": "GetBisPolicyRates retrieves central bank policy rates from BIS.", "operationId": "GetBisPolicyRates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBisPolicyRatesResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetBisPolicyRates", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-energy-capacity": { "get": { "description": "GetEnergyCapacity retrieves installed capacity data (solar, wind, coal) from EIA.", "operationId": "GetEnergyCapacity", "parameters": [ { "description": "Energy source codes to query (e.g., \"SUN\", \"WND\", \"COL\").\n Empty returns all tracked sources (SUN, WND, COL).", "in": "query", "name": "energy_sources", "required": false, "schema": { "type": "string" } }, { "description": "Number of years of historical data. Default 20 if not set.", "in": "query", "name": "years", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEnergyCapacityResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetEnergyCapacity", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-energy-prices": { "get": { "description": "GetEnergyPrices retrieves current energy commodity prices from EIA.", "operationId": "GetEnergyPrices", "parameters": [ { "description": "Optional commodity filter. Empty returns all tracked commodities.", "in": "query", "name": "commodities", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEnergyPricesResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetEnergyPrices", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-fred-series": { "get": { "description": "GetFredSeries retrieves time series data from the Federal Reserve Economic Data.", "operationId": "GetFredSeries", "parameters": [ { "description": "FRED series ID (e.g., \"GDP\", \"UNRATE\", \"CPIAUCSL\").", "in": "query", "name": "series_id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of observations to return. Defaults to 120.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFredSeriesResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetFredSeries", "tags": [ "EconomicService" ] } }, "/api/economic/v1/get-macro-signals": { "get": { "description": "GetMacroSignals computes 7 macro signals from 6 upstream sources with BUY/CASH verdict.", "operationId": "GetMacroSignals", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMacroSignalsResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "GetMacroSignals", "tags": [ "EconomicService" ] } }, "/api/economic/v1/list-world-bank-indicators": { "get": { "description": "ListWorldBankIndicators retrieves development indicator data from the World Bank.", "operationId": "ListWorldBankIndicators", "parameters": [ { "description": "World Bank indicator code (e.g., \"NY.GDP.MKTP.CD\").", "in": "query", "name": "indicator_code", "required": false, "schema": { "type": "string" } }, { "description": "Optional country filter (ISO 3166-1 alpha-2).", "in": "query", "name": "country_code", "required": false, "schema": { "type": "string" } }, { "description": "Optional year filter. Defaults to latest available.", "in": "query", "name": "year", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Maximum items per page.", "in": "query", "name": "page_size", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Cursor for next page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorldBankIndicatorsResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }, "description": "Validation error" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error response" } }, "summary": "ListWorldBankIndicators", "tags": [ "EconomicService" ] } } } }