Files
worldmonitor/docs/api/MarketService.openapi.yaml
Elie Habib 4816e27d3c fix(scripts): sync package-lock.json with h3-js dependency (#1254)
* Add premium stock analysis for finance variant

* fix(scripts): sync package-lock.json with h3-js dependency

Railway npm ci requires lock file in sync with package.json.

* fix(market): narrow undefined check for TS strict null safety
2026-03-08 08:45:12 +04:00

905 lines
35 KiB
YAML

openapi: 3.1.0
info:
title: MarketService API
version: 1.0.0
paths:
/api/market/v1/list-market-quotes:
get:
tags:
- MarketService
summary: ListMarketQuotes
description: ListMarketQuotes retrieves stock and index quotes.
operationId: ListMarketQuotes
parameters:
- name: symbols
in: query
description: Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListMarketQuotesResponse'
"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/market/v1/list-crypto-quotes:
get:
tags:
- MarketService
summary: ListCryptoQuotes
description: ListCryptoQuotes retrieves cryptocurrency quotes from CoinGecko.
operationId: ListCryptoQuotes
parameters:
- name: ids
in: query
description: Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns defaults.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListCryptoQuotesResponse'
"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/market/v1/list-commodity-quotes:
get:
tags:
- MarketService
summary: ListCommodityQuotes
description: ListCommodityQuotes retrieves commodity price quotes from Yahoo Finance.
operationId: ListCommodityQuotes
parameters:
- name: symbols
in: query
description: Commodity symbols to retrieve (Yahoo symbols). Empty returns defaults.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListCommodityQuotesResponse'
"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/market/v1/get-sector-summary:
get:
tags:
- MarketService
summary: GetSectorSummary
description: GetSectorSummary retrieves market sector performance data from Finnhub.
operationId: GetSectorSummary
parameters:
- name: period
in: query
description: Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d".
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetSectorSummaryResponse'
"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/market/v1/list-stablecoin-markets:
get:
tags:
- MarketService
summary: ListStablecoinMarkets
description: ListStablecoinMarkets retrieves stablecoin peg health and market data from CoinGecko.
operationId: ListStablecoinMarkets
parameters:
- name: coins
in: query
description: CoinGecko IDs to retrieve (e.g. "tether,usd-coin"). Empty returns defaults.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListStablecoinMarketsResponse'
"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/market/v1/list-etf-flows:
get:
tags:
- MarketService
summary: ListEtfFlows
description: ListEtfFlows retrieves BTC spot ETF flow estimates from Yahoo Finance.
operationId: ListEtfFlows
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEtfFlowsResponse'
"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/market/v1/get-country-stock-index:
get:
tags:
- MarketService
summary: GetCountryStockIndex
description: GetCountryStockIndex retrieves the primary stock index for a country from Yahoo Finance.
operationId: GetCountryStockIndex
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "JP").
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryStockIndexResponse'
"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/market/v1/list-gulf-quotes:
get:
tags:
- MarketService
summary: ListGulfQuotes
description: ListGulfQuotes retrieves Gulf region market quotes (indices, currencies, oil).
operationId: ListGulfQuotes
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListGulfQuotesResponse'
"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/market/v1/analyze-stock:
get:
tags:
- MarketService
summary: AnalyzeStock
description: AnalyzeStock retrieves a premium stock analysis report with technicals, news, and AI synthesis.
operationId: AnalyzeStock
parameters:
- name: symbol
in: query
required: false
schema:
type: string
- name: name
in: query
required: false
schema:
type: string
- name: include_news
in: query
required: false
schema:
type: boolean
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyzeStockResponse'
"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.
ListMarketQuotesRequest:
type: object
properties:
symbols:
type: array
items:
type: string
description: Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults.
description: ListMarketQuotesRequest specifies which stock/index symbols to retrieve.
ListMarketQuotesResponse:
type: object
properties:
quotes:
type: array
items:
$ref: '#/components/schemas/MarketQuote'
finnhubSkipped:
type: boolean
description: True when the Finnhub API key is not configured and stock quotes were skipped.
skipReason:
type: string
description: Human-readable reason when Finnhub was skipped (e.g., "FINNHUB_API_KEY not configured").
rateLimited:
type: boolean
description: True when the upstream API rate-limited the request.
description: ListMarketQuotesResponse contains stock and index quotes.
MarketQuote:
type: object
properties:
symbol:
type: string
minLength: 1
description: Ticker symbol (e.g., "AAPL", "^GSPC").
name:
type: string
description: Human-readable name.
display:
type: string
description: Display label.
price:
type: number
format: double
description: Current price.
change:
type: number
format: double
description: Percentage change from previous close.
sparkline:
type: array
items:
type: number
format: double
description: Sparkline data points (recent price history).
required:
- symbol
description: MarketQuote represents a stock or index quote from Finnhub or Yahoo Finance.
ListCryptoQuotesRequest:
type: object
properties:
ids:
type: array
items:
type: string
description: Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns defaults.
description: ListCryptoQuotesRequest specifies which cryptocurrencies to retrieve.
ListCryptoQuotesResponse:
type: object
properties:
quotes:
type: array
items:
$ref: '#/components/schemas/CryptoQuote'
description: ListCryptoQuotesResponse contains cryptocurrency quotes.
CryptoQuote:
type: object
properties:
name:
type: string
description: Cryptocurrency name (e.g., "Bitcoin").
symbol:
type: string
minLength: 1
description: Ticker symbol (e.g., "BTC").
price:
type: number
format: double
description: Current price in USD.
change:
type: number
format: double
description: 24-hour percentage change.
sparkline:
type: array
items:
type: number
format: double
description: Sparkline data points (recent price history).
required:
- symbol
description: CryptoQuote represents a cryptocurrency quote from CoinGecko.
ListCommodityQuotesRequest:
type: object
properties:
symbols:
type: array
items:
type: string
description: Commodity symbols to retrieve (Yahoo symbols). Empty returns defaults.
description: ListCommodityQuotesRequest specifies which commodities to retrieve.
ListCommodityQuotesResponse:
type: object
properties:
quotes:
type: array
items:
$ref: '#/components/schemas/CommodityQuote'
description: ListCommodityQuotesResponse contains commodity quotes.
CommodityQuote:
type: object
properties:
symbol:
type: string
minLength: 1
description: Commodity symbol (e.g., "CL=F" for crude oil).
name:
type: string
description: Human-readable name.
display:
type: string
description: Display label.
price:
type: number
format: double
description: Current price.
change:
type: number
format: double
description: Percentage change from previous close.
sparkline:
type: array
items:
type: number
format: double
description: Sparkline data points.
required:
- symbol
description: CommodityQuote represents a commodity price quote from Yahoo Finance.
GetSectorSummaryRequest:
type: object
properties:
period:
type: string
description: Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d".
description: GetSectorSummaryRequest specifies parameters for retrieving sector performance.
GetSectorSummaryResponse:
type: object
properties:
sectors:
type: array
items:
$ref: '#/components/schemas/SectorPerformance'
description: GetSectorSummaryResponse contains sector performance data.
SectorPerformance:
type: object
properties:
symbol:
type: string
minLength: 1
description: Sector symbol.
name:
type: string
description: Sector name.
change:
type: number
format: double
description: Percentage change over the measured period.
required:
- symbol
description: SectorPerformance represents performance data for a market sector.
ListStablecoinMarketsRequest:
type: object
properties:
coins:
type: array
items:
type: string
description: CoinGecko IDs to retrieve (e.g. "tether,usd-coin"). Empty returns defaults.
description: ListStablecoinMarketsRequest specifies which stablecoins to retrieve.
ListStablecoinMarketsResponse:
type: object
properties:
timestamp:
type: string
description: Timestamp of the data fetch (ISO 8601).
summary:
$ref: '#/components/schemas/StablecoinSummary'
stablecoins:
type: array
items:
$ref: '#/components/schemas/Stablecoin'
description: ListStablecoinMarketsResponse contains stablecoin market data.
StablecoinSummary:
type: object
properties:
totalMarketCap:
type: number
format: double
description: Total market cap across all queried stablecoins.
totalVolume24h:
type: number
format: double
description: Total 24h volume across all queried stablecoins.
coinCount:
type: integer
format: int32
description: Number of stablecoins returned.
depeggedCount:
type: integer
format: int32
description: Number of stablecoins in DEPEGGED state.
healthStatus:
type: string
description: 'Overall health: "HEALTHY", "CAUTION", or "WARNING".'
description: StablecoinSummary contains aggregate stablecoin market stats.
Stablecoin:
type: object
properties:
id:
type: string
minLength: 1
description: CoinGecko ID.
symbol:
type: string
minLength: 1
description: Ticker symbol (e.g. "USDT").
name:
type: string
description: Human-readable name.
price:
type: number
minimum: 0
format: double
description: Current price in USD.
deviation:
type: number
format: double
description: Deviation from $1.00 peg, as a percentage.
pegStatus:
type: string
description: 'Peg status: "ON PEG", "SLIGHT DEPEG", or "DEPEGGED".'
marketCap:
type: number
format: double
description: Market capitalization in USD.
volume24h:
type: number
format: double
description: 24-hour trading volume in USD.
change24h:
type: number
format: double
description: 24-hour price change percentage.
change7d:
type: number
format: double
description: 7-day price change percentage.
image:
type: string
description: Coin image URL.
required:
- id
- symbol
description: Stablecoin represents a single stablecoin with peg health data.
ListEtfFlowsRequest:
type: object
description: ListEtfFlowsRequest is empty; the handler uses a fixed list of BTC spot ETFs.
ListEtfFlowsResponse:
type: object
properties:
timestamp:
type: string
description: Timestamp of the data fetch (ISO 8601).
summary:
$ref: '#/components/schemas/EtfFlowsSummary'
etfs:
type: array
items:
$ref: '#/components/schemas/EtfFlow'
rateLimited:
type: boolean
description: True when the upstream API rate-limited the request.
description: ListEtfFlowsResponse contains BTC spot ETF flow data.
EtfFlowsSummary:
type: object
properties:
etfCount:
type: integer
format: int32
description: Number of ETFs with data.
totalVolume:
type: integer
format: int64
description: 'Total volume across all ETFs.. Warning: Values > 2^53 may lose precision in JavaScript'
totalEstFlow:
type: integer
format: int64
description: 'Total estimated flow across all ETFs.. Warning: Values > 2^53 may lose precision in JavaScript'
netDirection:
type: string
description: 'Net direction: "NET INFLOW", "NET OUTFLOW", or "NEUTRAL".'
inflowCount:
type: integer
format: int32
description: Number of ETFs with inflow.
outflowCount:
type: integer
format: int32
description: Number of ETFs with outflow.
description: EtfFlowsSummary contains aggregate ETF flow stats.
EtfFlow:
type: object
properties:
ticker:
type: string
minLength: 1
description: Ticker symbol (e.g. "IBIT").
issuer:
type: string
description: Fund issuer (e.g. "BlackRock").
price:
type: number
format: double
description: Latest closing price.
priceChange:
type: number
format: double
description: Day-over-day price change percentage.
volume:
type: integer
format: int64
description: 'Latest daily volume.. Warning: Values > 2^53 may lose precision in JavaScript'
avgVolume:
type: integer
format: int64
description: 'Average volume over prior days.. Warning: Values > 2^53 may lose precision in JavaScript'
volumeRatio:
type: number
format: double
description: Volume ratio (latest / average).
direction:
type: string
description: 'Flow direction: "inflow", "outflow", or "neutral".'
estFlow:
type: integer
format: int64
description: 'Estimated dollar flow magnitude.. Warning: Values > 2^53 may lose precision in JavaScript'
required:
- ticker
description: EtfFlow represents a single ETF with estimated flow data.
GetCountryStockIndexRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "JP").
required:
- countryCode
description: GetCountryStockIndexRequest specifies which country's stock index to retrieve.
GetCountryStockIndexResponse:
type: object
properties:
available:
type: boolean
description: Whether stock index data is available for this country.
code:
type: string
description: ISO 3166-1 alpha-2 country code.
symbol:
type: string
description: Ticker symbol (e.g., "^GSPC").
indexName:
type: string
description: Index name (e.g., "S&P 500").
price:
type: number
format: double
description: Latest closing price.
weekChangePercent:
type: number
format: double
description: Weekly change percentage.
currency:
type: string
description: Currency of the index.
fetchedAt:
type: string
description: When the data was fetched (ISO 8601).
description: GetCountryStockIndexResponse contains the country's primary stock index data.
ListGulfQuotesRequest:
type: object
ListGulfQuotesResponse:
type: object
properties:
quotes:
type: array
items:
$ref: '#/components/schemas/GulfQuote'
rateLimited:
type: boolean
GulfQuote:
type: object
properties:
symbol:
type: string
name:
type: string
flag:
type: string
country:
type: string
type:
type: string
price:
type: number
format: double
change:
type: number
format: double
sparkline:
type: array
items:
type: number
format: double
description: GulfQuote represents a Gulf region market quote (index, currency, or oil).
AnalyzeStockRequest:
type: object
properties:
symbol:
type: string
maxLength: 32
minLength: 1
name:
type: string
maxLength: 120
includeNews:
type: boolean
required:
- symbol
AnalyzeStockResponse:
type: object
properties:
available:
type: boolean
symbol:
type: string
name:
type: string
display:
type: string
currency:
type: string
currentPrice:
type: number
format: double
changePercent:
type: number
format: double
signalScore:
type: number
format: double
signal:
type: string
trendStatus:
type: string
volumeStatus:
type: string
macdStatus:
type: string
rsiStatus:
type: string
summary:
type: string
action:
type: string
confidence:
type: string
technicalSummary:
type: string
newsSummary:
type: string
whyNow:
type: string
bullishFactors:
type: array
items:
type: string
riskFactors:
type: array
items:
type: string
supportLevels:
type: array
items:
type: number
format: double
resistanceLevels:
type: array
items:
type: number
format: double
headlines:
type: array
items:
$ref: '#/components/schemas/StockAnalysisHeadline'
ma5:
type: number
format: double
ma10:
type: number
format: double
ma20:
type: number
format: double
ma60:
type: number
format: double
biasMa5:
type: number
format: double
biasMa10:
type: number
format: double
biasMa20:
type: number
format: double
volumeRatio5d:
type: number
format: double
rsi12:
type: number
format: double
macdDif:
type: number
format: double
macdDea:
type: number
format: double
macdBar:
type: number
format: double
provider:
type: string
model:
type: string
fallback:
type: boolean
newsSearched:
type: boolean
generatedAt:
type: string
StockAnalysisHeadline:
type: object
properties:
title:
type: string
source:
type: string
link:
type: string
publishedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'