Files
worldmonitor/docs/api/MarketService.openapi.yaml
Elie Habib 2b189b77b6 feat(stocks): add dividend growth analysis to stock analysis panel (#2927)
* feat(stocks): add dividend growth analysis to stock analysis panel

Shows yield, 5Y CAGR, frequency (quarterly/monthly/annual), payout
ratio, and ex-dividend date. Hidden for non-dividend stocks. Data
from Yahoo Finance dividend history.

* fix(stocks): bump cache key + fix partial-year CAGR + remove misleading avg yield

* fix(stocks): hydrate payout ratio, drop dead five-year yield, currency-aware dividend rate

- Add fetchPayoutRatio helper that calls Yahoo quoteSummary's summaryDetail
  module in parallel with the dividend chart fetch and returns the raw 0-1
  payout ratio (or undefined when missing/non-positive). The chart endpoint
  alone never returns payoutRatio, which is why it was hardcoded to 0.
- Make payout_ratio optional in proto and DividendProfile so a missing value
  is undefined instead of 0; remove five_year_avg_dividend_yield entirely
  (proto reserved 51) since it was always returned as 0 and never wired up.
- StockAnalysisPanel.renderDividendProfile now omits the Payout Ratio cell
  unless the value is present and > 0, formats it as (raw * 100).toFixed(1)%,
  and renders the dividend rate via Intl.NumberFormat with item.currency so
  EUR/GBP/JPY tickers no longer get a hardcoded "$" prefix.
- Bump live cache key v2 -> v3 so any cached snapshots persisted with the
  old shape are refetched once.
- Tests cover: payoutRatio populated from summaryDetail, payoutRatio
  undefined when summaryDetail returns 500 or raw=0, dividend response
  shape no longer contains fiveYearAvgDividendYield.

* fix(stocks): bump persisted history store to v3 to rotate pre-PR snapshots

Live analyze-stock cache was already bumped to v3, but the persisted
history store (premium-stock-store.ts) still used v2 keys for index/item
lookups. Pre-PR snapshots without the new dividend fields could pass the
age-only freshness check and suppress a live refetch, leaving the new
dividend section missing for up to 15 minutes.

Bumping the persisted store keys to v3 makes old snapshots invisible.
The data loader sees an empty history, triggers a live refetch, and
repopulates under the new v3 keys. Old v2 keys expire via TTL.

* fix(stocks): compute dividend CAGR correctly for quarterly/semiannual/annual payers

Previously computeDividendCagr() required at least 10 distinct dividend
months for a year to count as "full", which excluded every non-monthly
dividend payer (quarterly = 4 months, semiannual = 2, annual = 1).
CAGR therefore collapsed to 0/N/A for most ordinary dividend stocks.

The new check uses calendar position: any year strictly earlier than the
current calendar year is treated as complete, and the current in-progress
year is excluded to avoid penalizing stocks whose next payment has not
yet landed.

* test(stocks): pass analystData to buildAnalysisResponse after rebase onto #2926
2026-04-11 16:27:51 +04:00

1730 lines
64 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'
/api/market/v1/get-stock-analysis-history:
get:
tags:
- MarketService
summary: GetStockAnalysisHistory
description: GetStockAnalysisHistory retrieves shared premium stock analysis history from the backend store.
operationId: GetStockAnalysisHistory
parameters:
- name: symbols
in: query
required: false
schema:
type: string
- name: limit_per_symbol
in: query
required: false
schema:
type: integer
format: int32
- name: include_news
in: query
required: false
schema:
type: boolean
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetStockAnalysisHistoryResponse'
"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/backtest-stock:
get:
tags:
- MarketService
summary: BacktestStock
description: BacktestStock replays premium stock-analysis signals over recent price history.
operationId: BacktestStock
parameters:
- name: symbol
in: query
required: false
schema:
type: string
- name: name
in: query
required: false
schema:
type: string
- name: eval_window_days
in: query
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BacktestStockResponse'
"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-stored-stock-backtests:
get:
tags:
- MarketService
summary: ListStoredStockBacktests
description: ListStoredStockBacktests retrieves stored premium backtest snapshots from the backend store.
operationId: ListStoredStockBacktests
parameters:
- name: symbols
in: query
required: false
schema:
type: string
- name: eval_window_days
in: query
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListStoredStockBacktestsResponse'
"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-sectors:
get:
tags:
- MarketService
summary: ListCryptoSectors
description: ListCryptoSectors retrieves crypto sector performance averages.
operationId: ListCryptoSectors
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListCryptoSectorsResponse'
"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-defi-tokens:
get:
tags:
- MarketService
summary: ListDefiTokens
description: ListDefiTokens retrieves DeFi token prices and changes.
operationId: ListDefiTokens
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListDefiTokensResponse'
"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-ai-tokens:
get:
tags:
- MarketService
summary: ListAiTokens
description: ListAiTokens retrieves AI-focused crypto token prices and changes.
operationId: ListAiTokens
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListAiTokensResponse'
"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-other-tokens:
get:
tags:
- MarketService
summary: ListOtherTokens
description: ListOtherTokens retrieves other/trending crypto token prices and changes.
operationId: ListOtherTokens
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListOtherTokensResponse'
"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-fear-greed-index:
get:
tags:
- MarketService
summary: GetFearGreedIndex
description: GetFearGreedIndex retrieves the composite Fear & Greed sentiment index.
operationId: GetFearGreedIndex
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFearGreedIndexResponse'
"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-earnings-calendar:
get:
tags:
- MarketService
summary: ListEarningsCalendar
description: ListEarningsCalendar retrieves upcoming and recent earnings releases.
operationId: ListEarningsCalendar
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/ListEarningsCalendarResponse'
"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-cot-positioning:
get:
tags:
- MarketService
summary: GetCotPositioning
description: GetCotPositioning retrieves CFTC COT institutional positioning data.
operationId: GetCotPositioning
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCotPositioningResponse'
"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).
change7d:
type: number
format: double
description: 7-day percentage change.
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
analysisId:
type: string
analysisAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
stopLoss:
type: number
format: double
takeProfit:
type: number
format: double
engineVersion:
type: string
analystConsensus:
$ref: '#/components/schemas/AnalystConsensus'
priceTarget:
$ref: '#/components/schemas/PriceTarget'
recentUpgrades:
type: array
items:
$ref: '#/components/schemas/UpgradeDowngrade'
dividendYield:
type: number
format: double
trailingAnnualDividendRate:
type: number
format: double
exDividendDate:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
payoutRatio:
type: number
format: double
dividendFrequency:
type: string
dividendCagr:
type: number
format: double
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'
AnalystConsensus:
type: object
properties:
strongBuy:
type: integer
format: int32
buy:
type: integer
format: int32
hold:
type: integer
format: int32
sell:
type: integer
format: int32
strongSell:
type: integer
format: int32
total:
type: integer
format: int32
period:
type: string
PriceTarget:
type: object
properties:
high:
type: number
format: double
low:
type: number
format: double
mean:
type: number
format: double
median:
type: number
format: double
current:
type: number
format: double
numberOfAnalysts:
type: integer
format: int32
UpgradeDowngrade:
type: object
properties:
firm:
type: string
toGrade:
type: string
fromGrade:
type: string
action:
type: string
epochGradeDate:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
GetStockAnalysisHistoryRequest:
type: object
properties:
symbols:
type: array
items:
type: string
limitPerSymbol:
type: integer
maximum: 32
minimum: 1
format: int32
includeNews:
type: boolean
GetStockAnalysisHistoryResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/StockAnalysisHistoryItem'
StockAnalysisHistoryItem:
type: object
properties:
symbol:
type: string
snapshots:
type: array
items:
$ref: '#/components/schemas/AnalyzeStockResponse'
BacktestStockRequest:
type: object
properties:
symbol:
type: string
maxLength: 32
minLength: 1
name:
type: string
maxLength: 120
evalWindowDays:
type: integer
maximum: 30
minimum: 3
format: int32
required:
- symbol
BacktestStockResponse:
type: object
properties:
available:
type: boolean
symbol:
type: string
name:
type: string
display:
type: string
currency:
type: string
evalWindowDays:
type: integer
format: int32
evaluationsRun:
type: integer
format: int32
actionableEvaluations:
type: integer
format: int32
winRate:
type: number
format: double
directionAccuracy:
type: number
format: double
avgSimulatedReturnPct:
type: number
format: double
cumulativeSimulatedReturnPct:
type: number
format: double
latestSignal:
type: string
latestSignalScore:
type: number
format: double
summary:
type: string
generatedAt:
type: string
evaluations:
type: array
items:
$ref: '#/components/schemas/BacktestStockEvaluation'
engineVersion:
type: string
BacktestStockEvaluation:
type: object
properties:
analysisAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
signal:
type: string
signalScore:
type: number
format: double
entryPrice:
type: number
format: double
exitPrice:
type: number
format: double
simulatedReturnPct:
type: number
format: double
directionCorrect:
type: boolean
outcome:
type: string
stopLoss:
type: number
format: double
takeProfit:
type: number
format: double
analysisId:
type: string
ListStoredStockBacktestsRequest:
type: object
properties:
symbols:
type: array
items:
type: string
evalWindowDays:
type: integer
maximum: 30
minimum: 3
format: int32
ListStoredStockBacktestsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/BacktestStockResponse'
ListCryptoSectorsRequest:
type: object
description: ListCryptoSectorsRequest retrieves crypto sector performance.
ListCryptoSectorsResponse:
type: object
properties:
sectors:
type: array
items:
$ref: '#/components/schemas/CryptoSector'
description: ListCryptoSectorsResponse contains crypto sector performance data.
CryptoSector:
type: object
properties:
id:
type: string
description: Sector identifier.
name:
type: string
description: Sector display name.
change:
type: number
format: double
description: Average 24h percentage change across sector tokens.
description: CryptoSector represents performance data for a crypto market sector.
ListDefiTokensRequest:
type: object
description: ListDefiTokensRequest retrieves DeFi token prices.
ListDefiTokensResponse:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/CryptoQuote'
description: ListDefiTokensResponse contains DeFi token price data.
ListAiTokensRequest:
type: object
description: ListAiTokensRequest retrieves AI crypto token prices.
ListAiTokensResponse:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/CryptoQuote'
description: ListAiTokensResponse contains AI token price data.
ListOtherTokensRequest:
type: object
description: ListOtherTokensRequest retrieves other/trending crypto token prices.
ListOtherTokensResponse:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/CryptoQuote'
description: ListOtherTokensResponse contains other token price data.
GetFearGreedIndexRequest:
type: object
GetFearGreedIndexResponse:
type: object
properties:
compositeScore:
type: number
format: double
compositeLabel:
type: string
previousScore:
type: number
format: double
seededAt:
type: string
sentiment:
$ref: '#/components/schemas/FearGreedCategory'
volatility:
$ref: '#/components/schemas/FearGreedCategory'
positioning:
$ref: '#/components/schemas/FearGreedCategory'
trend:
$ref: '#/components/schemas/FearGreedCategory'
breadth:
$ref: '#/components/schemas/FearGreedCategory'
momentum:
$ref: '#/components/schemas/FearGreedCategory'
liquidity:
$ref: '#/components/schemas/FearGreedCategory'
credit:
$ref: '#/components/schemas/FearGreedCategory'
macro:
$ref: '#/components/schemas/FearGreedCategory'
crossAsset:
$ref: '#/components/schemas/FearGreedCategory'
vix:
type: number
format: double
hySpread:
type: number
format: double
yield10y:
type: number
format: double
putCallRatio:
type: number
format: double
pctAbove200d:
type: number
format: double
cnnFearGreed:
type: number
format: double
cnnLabel:
type: string
aaiiBull:
type: number
format: double
aaiiBear:
type: number
format: double
fedRate:
type: string
unavailable:
type: boolean
fsiValue:
type: number
format: double
fsiLabel:
type: string
hygPrice:
type: number
format: double
tltPrice:
type: number
format: double
sectorPerformance:
type: array
items:
$ref: '#/components/schemas/FearGreedSectorPerformance'
FearGreedCategory:
type: object
properties:
score:
type: number
format: double
weight:
type: number
format: double
contribution:
type: number
format: double
degraded:
type: boolean
inputsJson:
type: string
FearGreedSectorPerformance:
type: object
properties:
symbol:
type: string
name:
type: string
change1d:
type: number
format: double
ListEarningsCalendarRequest:
type: object
properties:
fromDate:
type: string
toDate:
type: string
ListEarningsCalendarResponse:
type: object
properties:
earnings:
type: array
items:
$ref: '#/components/schemas/EarningsEntry'
fromDate:
type: string
toDate:
type: string
total:
type: integer
format: int32
unavailable:
type: boolean
EarningsEntry:
type: object
properties:
symbol:
type: string
company:
type: string
date:
type: string
hour:
type: string
epsEstimate:
type: number
format: double
revenueEstimate:
type: number
format: double
epsActual:
type: number
format: double
revenueActual:
type: number
format: double
hasActuals:
type: boolean
surpriseDirection:
type: string
GetCotPositioningRequest:
type: object
GetCotPositioningResponse:
type: object
properties:
instruments:
type: array
items:
$ref: '#/components/schemas/CotInstrument'
reportDate:
type: string
unavailable:
type: boolean
CotInstrument:
type: object
properties:
name:
type: string
code:
type: string
reportDate:
type: string
assetManagerLong:
type: string
format: int64
assetManagerShort:
type: string
format: int64
leveragedFundsLong:
type: string
format: int64
leveragedFundsShort:
type: string
format: int64
dealerLong:
type: string
format: int64
dealerShort:
type: string
format: int64
netPct:
type: number
format: double