Files
worldmonitor/docs/api/MarketService.openapi.yaml
Elie Habib 55c9c36de2 feat(stocks): add insider transaction tracking to stock analysis panel (#2928)
* feat(stocks): add insider transaction tracking to stock analysis panel

Shows 6-month insider buy/sell activity from Finnhub: total buys,
sells, net value, and recent named-exec transactions. Gracefully
skips when FINNHUB_API_KEY is unavailable.

* fix: add cache tier entry for get-insider-transactions route

* fix(stocks): add insider RPC to premium paths + fix empty/stale states

* fix(stocks): add insider RPC to premium paths + fix empty/stale states

- Add /api/market/v1/get-insider-transactions to PREMIUM_RPC_PATHS
- Return unavailable:false with empty transactions when Finnhub has no data
  (panel shows "No insider transactions" instead of "unavailable")
- Mark stale insider data on refresh failures to avoid showing outdated info
- Update test to match new empty-data behavior

* fix(stocks): unblock stock-analysis render and surface exercise-only insider activity

- loadStockAnalysis no longer awaits loadInsiderDataForPanel before
  panel.renderAnalyses. The insider fetch now fires in parallel after
  the primary render at both the cached-snapshot and live-fetch call
  sites. When insider data arrives, loadInsiderDataForPanel re-renders
  the panel so the section fills in asynchronously without holding up
  the analyst report on a secondary Finnhub RPC.
- Add transaction code 'M' (exercise / conversion of derivative) to
  the allowed set in get-insider-transactions so symbols whose only
  recent Form 4 activity is option/RSU exercises no longer appear as
  "No insider transactions in the last 6 months". Exercises do not
  contribute to buys/sells dollar totals because transactionPrice is
  the strike price, not a market transaction.
- Panel table now uses a neutral (dim) color for non-buy/non-sell
  rows (M rows) instead of the buy/sell green/red binary.
- Tests cover: exercise-only activity producing non-empty transactions
  with zero buys/sells, and blended P/S/M activity preserving all
  three rows.

* fix(stocks): prevent cached insider fetch from clobbering live render

- Cached-path insider enrichment only runs when no live fetch is coming
- Added generation counter to guard against concurrent loadStockAnalysis calls
- Stale insider fetches now no-op instead of reverting panel state

* fix(stocks): hide transient insider-unavailable flash and zero out strike-derived values

- renderInsiderSection returns empty string when insider data is not yet
  fetched, so the transient "Insider data unavailable" card no longer
  flashes on initial render before the RPC completes
- Exercise rows (code M) now carry value: 0 on the server and render a
  dash placeholder in the Value cell, matching how the buy/sell totals
  already exclude strike-derived dollar amounts

* fix(stocks): exclude non-market Form 4 codes (A/D/F) from insider buy/sell totals

Form 4 codes A (grant/award), D (disposition to issuer), and F (tax/exercise
payment) are not open-market trades and should not drive insider conviction
totals. Only P (open-market purchase) and S (open-market sale) now feed the
buy/sell aggregates. A/D/F rows are still surfaced in the transaction list
alongside M (exercise) with value zeroed out so the panel does not look empty.
2026-04-11 16:44:25 +04:00

1809 lines
67 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'
/api/market/v1/get-insider-transactions:
get:
tags:
- MarketService
summary: GetInsiderTransactions
description: GetInsiderTransactions retrieves SEC insider buy/sell activity from Finnhub.
operationId: GetInsiderTransactions
parameters:
- name: symbol
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetInsiderTransactionsResponse'
"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
GetInsiderTransactionsRequest:
type: object
properties:
symbol:
type: string
maxLength: 32
minLength: 1
required:
- symbol
GetInsiderTransactionsResponse:
type: object
properties:
unavailable:
type: boolean
symbol:
type: string
totalBuys:
type: number
format: double
totalSells:
type: number
format: double
netValue:
type: number
format: double
transactions:
type: array
items:
$ref: '#/components/schemas/InsiderTransaction'
fetchedAt:
type: string
InsiderTransaction:
type: object
properties:
name:
type: string
shares:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
value:
type: number
format: double
transactionCode:
type: string
transactionDate:
type: string