openapi: 3.1.0 info: title: MarketService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /api/market/v1/list-market-quotes: get: tags: - MarketService summary: ListMarketQuotes description: Retrieve stock and index quotes for requested symbols, with prices, price changes, display names, sparklines and snapshot metadata for market monitoring. operationId: ListMarketQuotes parameters: - name: symbols in: query description: Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults. required: false style: form explode: true example: - "AAPL" schema: type: array items: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "asOf": "example" "finnhubSkipped": true "quotes": - "change": 1.5 "display": "example" "name": "WorldMonitor Analyst" "price": 75.25 "sparkline": - 1.5 "symbol": "AAPL" "rateLimited": true "skipReason": "example" schema: $ref: '#/components/schemas/ListMarketQuotesResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-crypto-quotes: get: tags: - MarketService summary: ListCryptoQuotes description: ListCryptoQuotes returns price and 24h change for major coins or up to 25 CoinGecko ids from CoinPaprika or CoinGecko; 7d change and sparkline need CoinGecko. operationId: ListCryptoQuotes parameters: - name: ids in: query description: |- Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns the default crypto set. At most 25 IDs are accepted; the handler resolves them seed-first and fetches the remainder (gap) from the upstream provider. required: false style: form explode: true example: - "example" schema: type: array items: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "provider": "worldmonitor" "quotes": - "change": 1.5 "change7d": 1.5 "name": "WorldMonitor Analyst" "price": 75.25 "sparkline": - 1.5 "symbol": "AAPL" "unresolvedIds": - "example" schema: $ref: '#/components/schemas/ListCryptoQuotesResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-commodity-quotes: get: tags: - MarketService summary: ListCommodityQuotes description: |- ListCommodityQuotes retrieves commodity price quotes. Reads the seeded commodity snapshot; only symbols in the configured commodity set (shared/commodities.json) are supported. operationId: ListCommodityQuotes parameters: - name: symbols in: query description: |- Commodity symbols to retrieve (Yahoo symbols). Empty returns the seed defaults. Only symbols in the configured commodity set (shared/commodities.json) are supported; requesting an unsupported symbol returns HTTP 400. required: false style: form explode: true example: - "BZ=F" schema: type: array items: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "quotes": - "change": -1.05 "display": "Brent" "name": "Brent Crude Oil" "price": 91.6 "priceAt": 1794291360000 "priceBasis": "futures" "priceSource": "Yahoo Finance" "sparkline": - 93 - 92 - 91.6 "sparklineIntervalSeconds": 300 "sparklineStartAt": 1794290700000 "symbol": "BZ=F" schema: $ref: '#/components/schemas/ListCommodityQuotesResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-physical-premiums: get: tags: - MarketService summary: GetPhysicalPremiums description: |- GetPhysicalPremiums compares SGE gold/silver benchmark prints with the existing COMEX futures snapshot and returns every conversion input. PRO-gated. Requires entitlement tier >= 1. operationId: GetPhysicalPremiums security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: metals in: query description: Accepted values are "gold" and "silver". Empty returns both metals. required: false style: form explode: true example: - "gold" schema: type: array items: type: string pattern: ^(?:gold|silver)$ maxItems: 2 uniqueItems: true - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "fx": "asOf": "example" "pair": "example" "rate": 75.25 "source": "example" "premiums": - "computedAt": "2026-01-15T12:00:00Z" "metal": "example" "paper": "asOf": "example" "currency": "USD" "price": 75.25 "source": "example" "unit": "example" "physical": "asOf": "example" "currency": "USD" "price": 75.25 "source": "example" "unit": "example" "premiumPct": 1.5 schema: $ref: '#/components/schemas/GetPhysicalPremiumsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-physical-divergence-index: get: tags: - MarketService summary: GetPhysicalDivergenceIndex description: |- GetPhysicalDivergenceIndex classifies current physical premiums against their bounded trailing histories and returns an all-metal stress composite. PRO-gated. Requires entitlement tier >= 1. operationId: GetPhysicalDivergenceIndex security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: metals in: query description: Accepted values are "gold" and "silver". Empty returns both metals. required: false style: form explode: true example: - "gold" schema: type: array items: type: string pattern: ^(?:gold|silver)$ maxItems: 2 uniqueItems: true - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "composite": "index": 1.5 "methodologyVersion": "example" "reason": "" "state": "PHYSICAL_DIVERGENCE_STATE_OK" "weights": - "metal": "example" "methodologyVersion": "example" "weight": 1.5 "evaluatedAt": 1717200000000 "methodologyVersion": "example" "readings": - "delta20d": 1.5 "delta5d": 1.5 "historyKey": "example" "historyPoints": 1 "historyWindowEnd": "example" schema: $ref: '#/components/schemas/GetPhysicalDivergenceIndexResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-sector-summary: get: tags: - MarketService summary: GetSectorSummary description: GetSectorSummary returns daily percent change for 12 US sector ETFs (XLK, XLF, XLE and peers, plus SMH) from Finnhub quotes with a Yahoo Finance fallback. operationId: GetSectorSummary parameters: - name: period in: query description: |- Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d". Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: "1d" schema: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "sectors": - "change": 1.5 "name": "WorldMonitor Analyst" "symbol": "AAPL" schema: $ref: '#/components/schemas/GetSectorSummaryResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-stablecoin-markets: get: tags: - MarketService summary: ListStablecoinMarkets description: ListStablecoinMarkets returns price, peg deviation and status, market cap and volume for USDT, USDC, DAI, FDUSD and USDe, or up to 25 CoinGecko ids. operationId: ListStablecoinMarkets parameters: - name: coins in: query description: |- CoinGecko IDs to retrieve (e.g. "tether,usd-coin"). Empty returns defaults. Repeated (`?coins=tether&coins=dai`) and comma-joined (`?coins=tether,dai`) forms are equivalent. IDs are trimmed, lowercased, and de-duplicated; the request is capped at 25 IDs. An ID that is not shaped like a CoinGecko ID, that overflows the cap, or that no provider can resolve is reported in `unresolved` rather than dropped. The empty (default) request is served from the seeded snapshot alone and never reaches an upstream provider. Naming IDs explicitly opts into a bounded, cached provider lookup for any ID the snapshot does not carry. required: false style: form explode: true example: - "example" schema: type: array items: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "dataStatus": "example" "stablecoins": - "change24h": 1.5 "change7d": 1.5 "deviation": 1.5 "id": "example-id" "image": "example" "marketCap": 1.5 "symbol": "AAPL" "summary": "coinCount": 1 "depeggedCount": 1 "healthStatus": "example" "totalMarketCap": 1 "totalVolume24h": 1 "timestamp": "2026-01-15T12:00:00Z" "unresolved": - "id": "example-id" "reason": "example" schema: $ref: '#/components/schemas/ListStablecoinMarketsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-etf-flows: get: tags: - MarketService summary: ListEtfFlows description: ListEtfFlows returns price, volume and a volume-based flow estimate for 10 US spot bitcoin ETFs such as IBIT, FBTC and GBTC, via Alpha Vantage or Yahoo. operationId: ListEtfFlows parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "etfs": - "avgVolume": 1 "direction": "example" "estFlow": 1 "issuer": "example" "price": 75.25 "ticker": "AAPL" "rateLimited": true "summary": "etfCount": 1 "inflowCount": 1 "netDirection": "example" "outflowCount": 1 "totalEstFlow": 1 "timestamp": "2026-01-15T12:00:00Z" schema: $ref: '#/components/schemas/ListEtfFlowsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-country-stock-index: get: tags: - MarketService summary: GetCountryStockIndex description: GetCountryStockIndex returns a country's main stock index by ISO 3166-1 alpha-2 code, with last close, weekly percent change and currency 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: true example: "US" schema: type: string enum: - 'US' - 'GB' - 'DE' - 'FR' - 'JP' - 'CN' - 'HK' - 'IN' - 'KR' - 'TW' - 'AU' - 'BR' - 'CA' - 'MX' - 'AR' - 'RU' - 'ZA' - 'SA' - 'AE' - 'IL' - 'TR' - 'PL' - 'NL' - 'CH' - 'ES' - 'IT' - 'SE' - 'NO' - 'SG' - 'TH' - 'MY' - 'ID' - 'PH' - 'NZ' - 'EG' - 'CL' - 'PE' - 'AT' - 'BE' - 'FI' - 'DK' - 'IE' - 'PT' - 'CZ' - 'HU' - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "available": true "code": "US" "currency": "USD" "fetchedAt": "2026-01-15T12:00:00Z" "indexName": "WorldMonitor Analyst" schema: $ref: '#/components/schemas/GetCountryStockIndexResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-price-history: get: tags: - MarketService summary: GetPriceHistory description: GetPriceHistory returns daily Yahoo Finance closes over 1mo, 3mo, 6mo or 1y for up to four symbols from the commodity, market and Gulf quote sets. operationId: GetPriceHistory parameters: - name: symbols in: query description: |- Comma-separated Yahoo symbols, at most 4 (e.g. "GC=F,SI=F"). Only symbols carried by the commodity, market and Gulf quote sets are served; others are reported in `unavailable`. A single string because the widget relay sets each query parameter once. required: true example: "GC=F,SI=F" schema: type: string pattern: '^ *[A-Za-z0-9^=.&-]{1,20} *(, *[A-Za-z0-9^=.&-]{1,20} *){0,3}$' - name: range in: query description: 'Lookback window: 1mo, 3mo, 6mo or 1y. Empty means 3mo.' required: false example: "3mo" schema: type: string pattern: '^(1mo|3mo|6mo|1y)?$' - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "range": "3mo" "series": - "closes": - 4176.4 - 4183.1 - 4192 "currency": "USD" "name": "Gold" "symbol": "GC=F" "timestamps": - 1785542400000 - 1785628800000 - 1785715200000 - "closes": - 60.84 - 61.02 - 61.25 "currency": "USD" "name": "Silver" "symbol": "SI=F" "timestamps": - 1785542400000 - 1785628800000 - 1785715200000 "unavailable": [] schema: $ref: '#/components/schemas/GetPriceHistoryResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-gulf-quotes: get: tags: - MarketService summary: ListGulfQuotes description: ListGulfQuotes returns prices, percent change and sparklines for Gulf stock indices and ETFs, six GCC currencies, and WTI and Brent crude oil. operationId: ListGulfQuotes parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "quotes": - "change": 1.5 "country": "US" "flag": "example" "name": "WorldMonitor Analyst" "price": 75.25 "rateLimited": true schema: $ref: '#/components/schemas/ListGulfQuotesResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/analyze-stock: get: tags: - MarketService summary: AnalyzeStock description: AnalyzeStock retrieves a premium stock analysis report with technicals, news, and AI synthesis. PRO-gated. Requires entitlement tier >= 1. operationId: AnalyzeStock security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: symbol in: query description: Stock ticker symbol to analyze. required: true example: "AAPL" schema: type: string - name: name in: query description: Optional company display name used to disambiguate the symbol. required: false example: "WorldMonitor Analyst" schema: type: string - name: include_news in: query description: Whether to include recent news in the stock analysis. required: false example: true schema: type: boolean - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "action": "example" "analysisAt": 1717200000000 "analysisId": "example-id" "analystConsensus": "buy": 1 "hold": 1 "period": "daily" "sell": 1 "strongBuy": 1 "atr": 1.5 schema: $ref: '#/components/schemas/AnalyzeStockResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-stock-analysis-history: get: tags: - MarketService summary: GetStockAnalysisHistory description: GetStockAnalysisHistory retrieves shared premium stock analysis history from the backend store. PRO-gated. Requires entitlement tier >= 1. operationId: GetStockAnalysisHistory security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: symbols in: query description: Stock ticker symbols whose stored analysis history should be returned. required: false style: form explode: true example: - "AAPL" schema: type: array items: type: string - name: limit_per_symbol in: query description: Maximum number of history snapshots to return per symbol. required: false example: 25 schema: type: integer format: int32 - name: include_news in: query description: Whether history snapshots should include stored news summaries. required: false example: true schema: type: boolean - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "items": - "snapshots": - "action": "example" "analysisAt": 1717200000000 "analysisId": "example-id" "analystConsensus": "buy": 1 "hold": 1 "period": "daily" "sell": 1 "strongBuy": 1 "atr": 1.5 "symbol": "AAPL" schema: $ref: '#/components/schemas/GetStockAnalysisHistoryResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/backtest-stock: get: tags: - MarketService summary: BacktestStock description: BacktestStock replays the technical-only stock signal over recent price history. PRO-gated. Requires entitlement tier >= 1. operationId: BacktestStock security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: symbol in: query description: Stock ticker symbol to backtest. required: true example: "AAPL" schema: type: string - name: name in: query description: Optional company display name used to disambiguate the symbol. required: false example: "WorldMonitor Analyst" schema: type: string - name: eval_window_days in: query description: Evaluation window in days for simulated backtest outcomes. required: false example: 7 schema: type: integer format: int32 - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "actionableEvaluations": 1 "available": true "avgSimulatedReturnPct": 1.5 "cumulativeSimulatedReturnPct": 1.5 "currency": "USD" schema: $ref: '#/components/schemas/BacktestStockResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-stored-stock-backtests: get: tags: - MarketService summary: ListStoredStockBacktests description: ListStoredStockBacktests retrieves stored premium backtest snapshots from the backend store. PRO-gated. Requires entitlement tier >= 1. operationId: ListStoredStockBacktests security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: symbols in: query description: Stock ticker symbols whose stored backtests should be returned. required: false style: form explode: true example: - "AAPL" schema: type: array items: type: string - name: eval_window_days in: query description: Evaluation window in days used by stored backtests. required: false example: 7 schema: type: integer format: int32 - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "items": - "actionableEvaluations": 1 "available": true "avgSimulatedReturnPct": 1.5 "cumulativeSimulatedReturnPct": 1.5 "currency": "USD" schema: $ref: '#/components/schemas/ListStoredStockBacktestsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-crypto-sectors: get: tags: - MarketService summary: ListCryptoSectors description: ListCryptoSectors returns the average 24h price change of the tokens with data in eight crypto sectors, such as Layer 1, DeFi, AI and Memes, from CoinGecko. operationId: ListCryptoSectors parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "sectors": - "change": 1.5 "id": "example-id" "name": "WorldMonitor Analyst" schema: $ref: '#/components/schemas/ListCryptoSectorsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-defi-tokens: get: tags: - MarketService summary: ListDefiTokens description: ListDefiTokens returns USD price with 24h and 7d change for DeFi tokens such as Aave, Uniswap, Pendle and Lido, from CoinGecko with CoinPaprika fallback. operationId: ListDefiTokens parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "tokens": - "change": 1.5 "change7d": 1.5 "name": "WorldMonitor Analyst" "price": 75.25 "sparkline": - 1.5 "symbol": "AAPL" schema: $ref: '#/components/schemas/ListDefiTokensResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-ai-tokens: get: tags: - MarketService summary: ListAiTokens description: ListAiTokens returns USD price with 24h and 7d change for AI crypto tokens such as Bittensor, Render and Fetch.ai, from CoinGecko with CoinPaprika fallback. operationId: ListAiTokens parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "tokens": - "change": 1.5 "change7d": 1.5 "name": "WorldMonitor Analyst" "price": 75.25 "sparkline": - 1.5 "symbol": "AAPL" schema: $ref: '#/components/schemas/ListAiTokensResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-other-tokens: get: tags: - MarketService summary: ListOtherTokens description: ListOtherTokens returns USD price with 24h and 7d change for trending tokens such as Aptos, Sui, Celestia and Ondo, from CoinGecko with CoinPaprika fallback. operationId: ListOtherTokens parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "tokens": - "change": 1.5 "change7d": 1.5 "name": "WorldMonitor Analyst" "price": 75.25 "sparkline": - 1.5 "symbol": "AAPL" schema: $ref: '#/components/schemas/ListOtherTokensResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-fear-greed-index: get: tags: - MarketService summary: GetFearGreedIndex description: Review the composite Fear & Greed sentiment index with available survey, market breadth and component inputs, including degraded-data flags for market context. operationId: GetFearGreedIndex parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "aaiiBear": 1.5 "aaiiBull": 1.5 "breadth": "contribution": 1.5 "degraded": true "inputsJson": "example" "score": 42.5 "weight": 1.5 "cnnFearGreed": 1.5 "cnnLabel": "example" schema: $ref: '#/components/schemas/GetFearGreedIndexResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/list-earnings-calendar: get: tags: - MarketService summary: ListEarningsCalendar description: ListEarningsCalendar returns Finnhub earnings releases from the past week to 14 days ahead, with EPS and revenue estimates, actuals and beat or miss. operationId: ListEarningsCalendar parameters: - name: fromDate in: query description: Inclusive lower date bound in YYYY-MM-DD format. required: false example: "2026-01-15" schema: type: string - name: toDate in: query description: Inclusive upper date bound in YYYY-MM-DD format. required: false example: "2026-01-15" schema: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "asOf": "example" "earnings": - "company": "example" "date": "2026-01-15" "epsActual": 1.5 "epsEstimate": 1.5 "hasActuals": true "fromDate": "2026-01-15" "toDate": "2026-01-15" "total": 1 schema: $ref: '#/components/schemas/ListEarningsCalendarResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-cot-positioning: get: tags: - MarketService summary: GetCotPositioning description: GetCotPositioning returns weekly CFTC Commitments of Traders data by trader group for S&P 500, Nasdaq 100, Treasury, EUR, JPY, gold, silver and WTI futures. operationId: GetCotPositioning parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "instruments": - "assetManagerLong": "1717200000000" "assetManagerShort": "1717200000000" "code": "example" "dealerLong": "1717200000000" "dealerShort": "1717200000000" "reportDate": "2026-01-15" "unavailable": false schema: $ref: '#/components/schemas/GetCotPositioningResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-insider-transactions: get: tags: - MarketService summary: GetInsiderTransactions description: GetInsiderTransactions retrieves SEC insider buy/sell activity from Finnhub. PRO-gated. Requires entitlement tier >= 1. operationId: GetInsiderTransactions security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] parameters: - name: symbol in: query description: Stock ticker symbol for insider transaction lookup. required: true example: "AAPL" schema: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "fetchedAt": "2026-01-15T12:00:00Z" "netValue": 1.5 "symbol": "AAPL" "totalBuys": 1 "totalSells": 1 schema: $ref: '#/components/schemas/GetInsiderTransactionsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: PRO entitlement access denied. headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-market-breadth-history: get: tags: - MarketService summary: GetMarketBreadthHistory description: Review historical S&P 500 market breadth, including the percentage of stocks above 20, 50 and 200-day moving averages, with current readings and dated history. operationId: GetMarketBreadthHistory parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "currentPctAbove200d": 1.5 "currentPctAbove20d": 1.5 "currentPctAbove50d": 1.5 "history": - "date": "2026-01-15" "pctAbove200d": 1.5 "pctAbove20d": 1.5 "pctAbove50d": 1.5 "unavailable": false schema: $ref: '#/components/schemas/GetMarketBreadthHistoryResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-gold-intelligence: get: tags: - MarketService summary: GetGoldIntelligence description: GetGoldIntelligence returns gold and other precious metal prices, XAU in six currencies, gold/silver ratio, CFTC positioning, GLD holdings and IMF reserves. operationId: GetGoldIntelligence parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "cbReserves": "asOfMonth": "2026-09" "indicator": "IRFCLDT1_IRFCL56_USD" "topBuyers12m": [] "topHolders": - "iso3": "USA" "name": "United States" "pctOfReserves": 50 "tonnes": 0 "topSellers12m": [] "totalTonnes": 0 "valueIsOunces": false "crossCurrencyPrices": [] "drivers": [] "goldChangePct": 0 "goldPrice": 3200 "goldSparkline": [] "palladiumPrice": 0 "platinumPrice": 0 "silverPrice": 0 "unavailable": false "updatedAt": "2026-09-30T00:00:00Z" schema: $ref: '#/components/schemas/GetGoldIntelligenceResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/market/v1/get-hyperliquid-flow: get: tags: - MarketService summary: GetHyperliquidFlow description: GetHyperliquidFlow returns funding, open interest, 24h volume, basis and flow scores for Hyperliquid perps on crypto, metals, oil, gas and FX, every 5 min. operationId: GetHyperliquidFlow parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "assetCount": 1 "assets": - "alerts": - "example" "assetClass": "example" "basisScore": 42.5 "composite": 1.5 "dayNotional": "example" "fetchedAt": "2026-01-15T12:00:00Z" "ts": "1717200000000" "unavailable": false schema: $ref: '#/components/schemas/GetHyperliquidFlowResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). BearerAuth: type: http scheme: bearer description: 'Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer .' schemas: JmespathProjectionError: description: Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits. properties: _jmespath_error: description: Projection error discriminator and details. type: string original_keys: description: Top-level keys or shape of the unprojected response. items: type: string type: array required: - _jmespath_error - original_keys type: object UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: Returned when the API key is missing, malformed, or lacks current API access. 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. BillingVerificationError: type: object description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After." properties: error: type: string description: Human-readable billing-verification failure reason. code: type: string enum: - renewal_verification_pending - renewal_verification_failed - entitlement_verification_unavailable description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header. requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate. required: - error - code InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message GatewayError: type: object description: Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. code: type: string enum: - subscription_lapsed description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header). requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. 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. A configured key is not a live tape; this flag is configuration, not Tape Claim. 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. unavailableSymbols: type: array items: $ref: '#/components/schemas/MarketQuoteUnavailable' asOf: type: string 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. MarketQuoteUnavailable: type: object properties: symbol: type: string minLength: 1 description: The requested ticker symbol, normalized. reason: type: string enum: - MARKET_QUOTE_UNAVAILABLE_REASON_UNSPECIFIED - MARKET_QUOTE_UNAVAILABLE_REASON_NOT_FOUND - MARKET_QUOTE_UNAVAILABLE_REASON_PROVIDER_ERROR - MARKET_QUOTE_UNAVAILABLE_REASON_PROVIDER_RATE_LIMITED - MARKET_QUOTE_UNAVAILABLE_REASON_PROVIDER_NOT_CONFIGURED - MARKET_QUOTE_UNAVAILABLE_REASON_REQUEST_LIMIT_EXCEEDED - MARKET_QUOTE_UNAVAILABLE_REASON_UPSTREAM_BUDGET_EXHAUSTED - MARKET_QUOTE_UNAVAILABLE_REASON_SEED_UNAVAILABLE description: |- MarketQuoteUnavailableReason explains why a requested symbol produced no quote. Every symbol that survives normalization gets either a quote or one of these reasons. required: - symbol description: MarketQuoteUnavailable reports a requested symbol that produced no quote. ListCryptoQuotesRequest: type: object properties: ids: type: array items: type: string maxItems: 25 description: |- Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns the default crypto set. At most 25 IDs are accepted; the handler resolves them seed-first and fetches the remainder (gap) from the upstream provider. maxItems: 25 description: ListCryptoQuotesRequest specifies which cryptocurrencies to retrieve. ListCryptoQuotesResponse: type: object properties: quotes: type: array items: $ref: '#/components/schemas/CryptoQuote' unresolvedIds: type: array items: type: string description: |- CoinGecko IDs that were requested but could not be resolved from the seed or the upstream provider. Omitted IDs are never silently dropped. provider: type: string description: |- Data source for this response: "seed" (default set/seed hits only), "upstream" (at least one gap ID fetched from the provider), "mixed" (seed hits plus fetched gaps), or "degraded" (a gap fetch failed). 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 the seed defaults. Only symbols in the configured commodity set (shared/commodities.json) are supported; requesting an unsupported symbol returns HTTP 400. 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 closes, oldest first. Bars with no trades are left out. priceSource: type: string description: Observed price provider, when known for Brent and WTI. priceBasis: type: string description: '"futures" for a futures quote, "spot" for a daily spot observation.' priceAt: type: integer format: int64 description: 'Provider observation time in Unix epoch milliseconds, with daily spot dates represented at midnight UTC. Warning: Values > 2^53 may lose precision in JavaScript' sparklineIntervalSeconds: type: integer format: int32 description: 'Width of each sparkline bar in seconds: 300 for the 24-hour intraday series, 86400 for daily closes.' sparklineStartAt: type: integer format: int64 description: |- Start of the first sparkline bar in Unix epoch milliseconds. Later bars follow in trading order with closed periods left out, so only the first point's time is defined.. Warning: Values > 2^53 may lose precision in JavaScript required: - symbol description: CommodityQuote represents a commodity price observation. GetPhysicalPremiumsRequest: type: object properties: metals: type: array items: type: string pattern: ^(?:gold|silver)$ maxItems: 2 uniqueItems: true description: Accepted values are "gold" and "silver". Empty returns both metals. description: GetPhysicalPremiumsRequest optionally limits the response to gold or silver. GetPhysicalPremiumsResponse: type: object properties: premiums: type: array items: $ref: '#/components/schemas/PhysicalPremium' fx: $ref: '#/components/schemas/FxSnapshot' description: GetPhysicalPremiumsResponse contains the auditable benchmark comparison. PhysicalPremium: type: object properties: metal: type: string physical: $ref: '#/components/schemas/BenchmarkLeg' paper: $ref: '#/components/schemas/BenchmarkLeg' premiumUsdPerOz: type: number format: double premiumPct: type: number format: double computedAt: type: string description: PhysicalPremium compares an SGE physical benchmark with a COMEX future. BenchmarkLeg: type: object properties: price: type: number format: double currency: type: string unit: type: string source: type: string asOf: type: string description: BenchmarkLeg identifies one raw price and its observation clock. FxSnapshot: type: object properties: pair: type: string rate: type: number format: double source: type: string asOf: type: string description: FxSnapshot records the conversion input shared by both metals. GetPhysicalDivergenceIndexRequest: type: object properties: metals: type: array items: type: string pattern: ^(?:gold|silver)$ maxItems: 2 uniqueItems: true description: Accepted values are "gold" and "silver". Empty returns both metals. description: GetPhysicalDivergenceIndexRequest selects zero or more supported metals. GetPhysicalDivergenceIndexResponse: type: object properties: readings: type: array items: $ref: '#/components/schemas/PhysicalDivergenceReading' composite: $ref: '#/components/schemas/PhysicalStressComposite' evaluatedAt: type: integer format: int64 description: 'Evaluation time as Unix epoch milliseconds, or zero when unavailable.. Warning: Values > 2^53 may lose precision in JavaScript' methodologyVersion: type: string description: Methodology identifier for the complete response. description: GetPhysicalDivergenceIndexResponse returns metal readings and the composite. PhysicalDivergenceReading: type: object properties: metal: type: string description: 'Supported metal name: gold or silver.' state: type: string enum: - PHYSICAL_DIVERGENCE_STATE_UNSPECIFIED - PHYSICAL_DIVERGENCE_STATE_OK - PHYSICAL_DIVERGENCE_STATE_INSUFFICIENT_HISTORY - PHYSICAL_DIVERGENCE_STATE_STALE_INPUT - PHYSICAL_DIVERGENCE_STATE_MISSING_INPUT description: PhysicalDivergenceState is exhaustive for every divergence consumer. reason: type: string pattern: ^(?:|history_points_below_60|physical_print_older_than_12_calendar_days|paper_snapshot_older_than_36_hours|fx_snapshot_older_than_60_hours|current_premium_missing|evaluation_clock_invalid|physical_print_invalid|paper_snapshot_invalid|fx_snapshot_invalid|physical_print_in_future|paper_snapshot_in_future|fx_snapshot_in_future|history_window_not_aligned|history_values_invalid|divergence_snapshot_unavailable|divergence_methodology_unsupported)$ description: Machine-readable explanation for the state. regime: type: string enum: - PHYSICAL_PREMIUM_REGIME_UNSPECIFIED - PHYSICAL_PREMIUM_REGIME_NORMAL - PHYSICAL_PREMIUM_REGIME_ELEVATED - PHYSICAL_PREMIUM_REGIME_STRESSED - PHYSICAL_PREMIUM_REGIME_EXTREME description: PhysicalPremiumRegime classifies the normalized premium distribution. index: type: number format: double description: Normalized divergence index from 0 to 100. premiumPct: type: number format: double description: Current physical premium as a percentage. premiumUsdPerOz: type: number format: double description: Current physical premium in USD per troy ounce. percentile: type: number format: double description: Current premium's empirical percentile from 0 to 100. robustZ: type: number format: double description: Median-absolute-deviation robust z-score. delta5d: type: number format: double description: Premium change versus five observations earlier. delta20d: type: number format: double description: Premium change versus twenty observations earlier. trend5d: type: string enum: - PHYSICAL_PREMIUM_TREND_UNSPECIFIED - PHYSICAL_PREMIUM_TREND_WIDENING - PHYSICAL_PREMIUM_TREND_STABLE - PHYSICAL_PREMIUM_TREND_NARROWING description: PhysicalPremiumTrend describes a trailing premium direction. trend20d: type: string enum: - PHYSICAL_PREMIUM_TREND_UNSPECIFIED - PHYSICAL_PREMIUM_TREND_WIDENING - PHYSICAL_PREMIUM_TREND_STABLE - PHYSICAL_PREMIUM_TREND_NARROWING description: PhysicalPremiumTrend describes a trailing premium direction. historyPoints: type: integer format: int32 description: Number of valid observations available to the classifier. historyWindowStart: type: string description: Oldest observation date in the evaluated window, or empty when unavailable. historyWindowEnd: type: string description: Newest observation date in the evaluated window, or empty when unavailable. physicalAsOf: type: string description: Physical benchmark trading date in YYYY-MM-DD form, or empty when unavailable. paperAsOf: type: integer format: int64 description: 'Paper snapshot time as Unix epoch milliseconds, or zero when unavailable.. Warning: Values > 2^53 may lose precision in JavaScript' historyKey: type: string description: Redis history key used by the calculation. methodologyVersion: type: string description: Methodology identifier used by this reading. provenance: $ref: '#/components/schemas/PhysicalDivergenceProvenance' description: PhysicalDivergenceReading is one metal's normalized divergence result. PhysicalDivergenceProvenance: type: object properties: physicalSource: type: string description: Human-readable physical benchmark provider. physicalSymbol: type: string description: Physical benchmark contract symbol. physicalAsOf: type: string description: Physical benchmark trading date in YYYY-MM-DD form, or empty when unavailable. paperSource: type: string description: Human-readable paper benchmark provider, or empty when unavailable. paperSymbol: type: string description: Paper benchmark contract symbol. paperAsOf: type: integer format: int64 description: 'Paper snapshot time as Unix epoch milliseconds, or zero when unavailable.. Warning: Values > 2^53 may lose precision in JavaScript' fxSource: type: string description: Human-readable FX provider, or empty when unavailable. fxPair: type: string description: FX conversion pair. fxAsOf: type: integer format: int64 description: 'FX snapshot time as Unix epoch milliseconds, or zero when unavailable.. Warning: Values > 2^53 may lose precision in JavaScript' historyKey: type: string description: Redis history key used by the calculation. historyWindowPoints: type: integer format: int32 description: Maximum number of observations retained in history. methodologyVersion: type: string description: Methodology identifier used by this provenance record. description: PhysicalDivergenceProvenance preserves the exact inputs used for one reading. PhysicalStressComposite: type: object properties: state: type: string enum: - PHYSICAL_DIVERGENCE_STATE_UNSPECIFIED - PHYSICAL_DIVERGENCE_STATE_OK - PHYSICAL_DIVERGENCE_STATE_INSUFFICIENT_HISTORY - PHYSICAL_DIVERGENCE_STATE_STALE_INPUT - PHYSICAL_DIVERGENCE_STATE_MISSING_INPUT description: PhysicalDivergenceState is exhaustive for every divergence consumer. reason: type: string pattern: ^(?:|divergence_snapshot_unavailable|divergence_methodology_unsupported|member_not_ok:gold:missing_input|member_not_ok:silver:missing_input|member_not_ok:gold:stale_input|member_not_ok:silver:stale_input|member_not_ok:gold:insufficient_history|member_not_ok:silver:insufficient_history)$ description: Machine-readable explanation for the aggregate state. index: type: number format: double description: Weighted aggregate index from 0 to 100 when state is OK. weights: type: array items: $ref: '#/components/schemas/PhysicalStressWeight' methodologyVersion: type: string description: Methodology identifier used by the composite. description: PhysicalStressComposite combines the supported metals into one index. PhysicalStressWeight: type: object properties: metal: type: string description: 'Supported metal name: gold or silver.' weight: type: number format: double description: Composite weight from zero to one. methodologyVersion: type: string description: Methodology identifier used by this weight. description: PhysicalStressWeight records one metal's composite contribution. GetSectorSummaryRequest: type: object properties: period: type: string description: |- Time period for performance calculation (e.g., "1d", "1w", "1m"). Defaults to "1d". Accepted but currently ignored; no-op until this handler supports the parameter. 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. Repeated (`?coins=tether&coins=dai`) and comma-joined (`?coins=tether,dai`) forms are equivalent. IDs are trimmed, lowercased, and de-duplicated; the request is capped at 25 IDs. An ID that is not shaped like a CoinGecko ID, that overflows the cap, or that no provider can resolve is reported in `unresolved` rather than dropped. The empty (default) request is served from the seeded snapshot alone and never reaches an upstream provider. Naming IDs explicitly opts into a bounded, cached provider lookup for any ID the snapshot does not carry. 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' unresolved: type: array items: $ref: '#/components/schemas/UnresolvedStablecoin' dataStatus: type: string description: |- Coverage of THIS response, distinct from `summary.health_status` (which reports peg health, not data availability): "OK" — every requested coin was returned. "PARTIAL" — at least one coin returned, at least one unresolved. "UNAVAILABLE" — no coin data available. 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. UnresolvedStablecoin: type: object properties: id: type: string description: |- The requested ID, after trimming and lowercasing. Malformed IDs are reported as sent (normalized and truncated) so the caller can spot the typo. reason: type: string description: |- Bounded vocabulary — anything outside this list is a contract violation: "INVALID_ID" — not shaped like a CoinGecko ID. "OVER_CAP" — beyond the per-request ID cap; never looked up. "NOT_FOUND" — the provider answered, and has no such coin. "PROVIDER_ERROR" — the lookup failed, so the ID is unknown, not absent. description: UnresolvedStablecoin explains why a requested ID is absent from the response. 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. GetPriceHistoryRequest: type: object properties: symbols: type: string maxLength: 100 pattern: ^ *[A-Za-z0-9^=.&-]{1,20} *(, *[A-Za-z0-9^=.&-]{1,20} *){0,3}$ description: |- Comma-separated Yahoo symbols, at most 4 (e.g. "GC=F,SI=F"). Only symbols carried by the commodity, market and Gulf quote sets are served; others are reported in `unavailable`. A single string because the widget relay sets each query parameter once. range: type: string pattern: ^(1mo|3mo|6mo|1y)?$ description: 'Lookback window: 1mo, 3mo, 6mo or 1y. Empty means 3mo.' required: - symbols description: GetPriceHistoryRequest names up to four tracked Yahoo symbols and a lookback window. GetPriceHistoryResponse: type: object properties: range: type: string description: The lookback window that was served. series: type: array items: $ref: '#/components/schemas/PriceSeries' unavailable: type: array items: type: string description: |- Requested symbols reported unavailable because they are outside the tracked set or Yahoo could not serve them. description: GetPriceHistoryResponse contains one series per served symbol. PriceSeries: type: object properties: symbol: type: string description: Yahoo symbol (e.g. "GC=F"). name: type: string description: Display name (e.g. "Gold"). currency: type: string description: Quote currency reported by Yahoo (e.g. "USD"). timestamps: type: array items: type: integer format: int64 description: 'One timestamp per trading day, Unix epoch milliseconds, ascending.. Warning: Values > 2^53 may lose precision in JavaScript' closes: type: array items: type: number format: double description: Daily close for the timestamp at the same index. description: PriceSeries holds one symbol's daily closes as aligned parallel arrays. 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 description: Stock ticker symbol to analyze. name: type: string maxLength: 120 description: Optional company display name used to disambiguate the symbol. includeNews: type: boolean description: Whether to include recent news in the stock analysis. 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 description: |- Technical-analysis score (0-100), retained as a stable pair with signal for clients that predate the fundamentals-blended rating. signal: type: string description: |- Technical-only signal paired with signal_score. New clients should use rating_signal with composite_score for the surfaced investment rating. 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 marketSession: type: string description: |- US-equity trading session at analysis time: "regular", "pre", "post" or "closed". Empty when session detection does not apply (non-US symbols). extendedPrice: type: number format: double description: |- Latest pre/post-market price from Yahoo extended-hours candles. Only set when market_session is "pre" or "post" and extended data is available. extendedChangePercent: type: number format: double description: |- Extended-hours change % vs the last regular-session close. Only set when extended_price is set. fundamentals: $ref: '#/components/schemas/Fundamentals' fundamentalScore: type: number format: double description: |- Fundamental health score (0-100) blended from the quality/growth/leverage fundamentals above. Unset when too few fundamentals are available to score, in which case composite_score falls back to signal_score. compositeScore: type: number format: double description: |- Blend of signal_score (technicals) and fundamental_score that drives rating_signal, so a Strong buy/sell no longer fires on price action alone. Equals signal_score when fundamental_score is unset. nextEarningsDate: type: string description: |- Next scheduled earnings date (YYYY-MM-DD) plus consensus EPS / revenue for the symbol, joined from the market:earnings-calendar:v1 seed. Unset when the symbol has no upcoming (not-yet-reported) entry in the seed's ~2-week window. (61-62 are taken by a concurrent PR; using 63-65 to avoid a field collision.) consensusEps: type: number format: double consensusRevenue: type: number format: double newsSentiment: type: number format: double description: |- LLM-derived news sentiment for the analyzed symbol: a signed score in [-1, 1] (-1 very bearish, 0 neutral / no material news, +1 very bullish), emitted by the same overlay model that already reads the headlines — no extra call. Omitted when the analysis falls back to rules (no LLM overlay). (69 avoids a field collision with in-flight PRs: 61-62 blend fundamentals into the rating, 63-65 are the merged earnings join, 66-68 are the in-flight risk-analytics PR.) realizedVolatility: type: number format: double description: |- Risk analytics computed from the 6-month daily candles already fetched for the technical snapshot (no extra upstream call). (66-68 avoid a field collision: 61-62 are claimed by the in-flight PR that blends fundamentals into the rating, and 63-65 by the merged earnings join.) Annualized realized volatility — sample stdev of daily log returns × √252 — as a fractional ratio where 0.25 means 25%. 0 when history is insufficient. atr: type: number format: double description: |- Wilder's 14-period Average True Range, in the response currency's price units. 0 when history is insufficient. maxDrawdown: type: number format: double description: |- Maximum peak-to-trough drawdown over the window, as a non-positive fractional ratio where -0.25 means a 25% decline. 0 for a monotonically rising series. ratingSignal: type: string description: |- Fundamentals-blended signal paired with composite_score. Kept separate from the legacy technical-only signal/signal_score pair so already-loaded web, desktop, and API clients never render a mixed-version rating. ratingSummary: type: string description: |- Fundamentals-blended narrative paired with rating_signal/composite_score. Legacy summary remains paired with signal/signal_score during rollout. ratingAction: type: string description: |- Fundamentals-blended action paired with rating_signal/composite_score. Legacy action remains paired with signal/signal_score during rollout. ratingConfidence: type: string description: |- Fundamentals-blended confidence paired with rating_signal/composite_score. Legacy confidence remains paired with signal/signal_score during rollout. ratingWhyNow: type: string description: |- Fundamentals-blended explanation paired with rating_signal/composite_score. Legacy why_now remains paired with signal/signal_score during rollout. ratingBullishFactors: type: array items: type: string description: |- Fundamentals-aware positive factors supporting the composite rating. Legacy bullish_factors remain technical-only during rollout. ratingRiskFactors: type: array items: type: string description: |- Fundamentals-aware risks supporting the composite rating. Legacy risk_factors remain technical-only during rollout. 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' marketSessionAtPublish: type: string description: |- US equity session at publish time: "regular", "pre", "post", or "closed". Empty when published_at is invalid or US hours do not apply. alignedTradingDate: type: string description: NYSE/Nasdaq trading date this headline aligns to (YYYY-MM-DD). Empty when unaligned. alignmentRule: type: string enum: - HEADLINE_ALIGNMENT_RULE_UNSPECIFIED - HEADLINE_ALIGNMENT_RULE_REGULAR_SESSION_SAME_TRADING_DAY - HEADLINE_ALIGNMENT_RULE_PREMARKET_SAME_TRADING_DAY - HEADLINE_ALIGNMENT_RULE_AFTER_HOURS_NEXT_TRADING_DAY - HEADLINE_ALIGNMENT_RULE_NON_SESSION_NEXT_TRADING_DAY - HEADLINE_ALIGNMENT_RULE_OVERNIGHT_SAME_TRADING_DAY description: |- How a headline's publish time was mapped onto a US equity trading date. Bookkeeping only — never a claim that the headline moved the tape. 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' Fundamentals: type: object properties: profitMargin: type: number format: double description: Fractional ratio where 0.25 means 25%. grossMargin: type: number format: double description: Fractional ratio where 0.25 means 25%. operatingMargin: type: number format: double description: Fractional ratio where 0.25 means 25%. returnOnEquity: type: number format: double description: Fractional ratio where 0.25 means 25%. returnOnAssets: type: number format: double description: Fractional ratio where 0.25 means 25%. revenueGrowth: type: number format: double description: Fractional ratio where 0.25 means 25%. earningsGrowth: type: number format: double description: Fractional ratio where 0.25 means 25%. debtToEquity: type: number format: double description: Normalized debt/equity ratio where 1.5 means debt is 1.5x equity. totalCash: type: number format: double description: Latest Yahoo financialData value denominated in financial_currency. totalDebt: type: number format: double description: Latest Yahoo financialData value denominated in financial_currency. freeCashflow: type: number format: double description: Latest Yahoo financialData value denominated in financial_currency. ebitda: type: number format: double description: Latest Yahoo financialData value denominated in financial_currency. financialCurrency: type: string description: |- ISO 4217 currency used by the company's financial statements. This can differ from AnalyzeStockResponse.currency for ADRs and cross-listings. GetStockAnalysisHistoryRequest: type: object properties: symbols: type: array items: type: string description: Stock ticker symbols whose stored analysis history should be returned. limitPerSymbol: type: integer maximum: 32 minimum: 1 format: int32 description: Maximum number of history snapshots to return per symbol. includeNews: type: boolean description: Whether history snapshots should include stored news summaries. 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 description: Stock ticker symbol to backtest. name: type: string maxLength: 120 description: Optional company display name used to disambiguate the symbol. evalWindowDays: type: integer maximum: 30 minimum: 3 format: int32 description: Evaluation window in days for simulated backtest outcomes. 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 ratingBasis: type: string description: |- "technical_only": historical Yahoo bars do not include point-in-time fundamentals, so this result must not be presented as a replay of the fundamentals-blended live rating. 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 description: Stock ticker symbols whose stored backtests should be returned. evalWindowDays: type: integer maximum: 30 minimum: 3 format: int32 description: Evaluation window in days used by stored backtests. 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 description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. fsiValue: type: number format: double description: |- Bespoke Fear & Greed header stress ratio, not the KCFSI/ECB FSI panel composite. Formula: (HYG / TLT) / (VIX * HY OAS / 100). fsiLabel: type: string description: |- Label for fsi_value: Low Stress (>=1.5), Moderate Stress (>=0.8), Elevated Stress (>=0.3), otherwise High Stress. hygPrice: type: number format: double description: Latest HYG ETF price used in the Fear & Greed header stress ratio. tltPrice: type: number format: double description: Latest TLT ETF price used in the Fear & Greed header stress ratio. 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 description: Inclusive lower date bound in YYYY-MM-DD format. toDate: type: string description: Inclusive upper date bound in YYYY-MM-DD format. 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 description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. asOf: type: string 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 description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. 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 smallTraderLong: type: string format: int64 description: |- Non-reportable positions are the CFTC series closest to small traders. They are a residual category, not a direct measurement of all retail flow. smallTraderShort: type: string format: int64 smallTraderAvailable: type: boolean description: False for cache rows written before the non-reportable fields were added. GetInsiderTransactionsRequest: type: object properties: symbol: type: string maxLength: 32 minLength: 1 description: Stock ticker symbol for insider transaction lookup. required: - symbol GetInsiderTransactionsResponse: type: object properties: unavailable: type: boolean description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. 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 GetMarketBreadthHistoryRequest: type: object GetMarketBreadthHistoryResponse: type: object properties: currentPctAbove20d: type: number format: double currentPctAbove50d: type: number format: double currentPctAbove200d: type: number format: double updatedAt: type: string history: type: array items: $ref: '#/components/schemas/BreadthSnapshot' unavailable: type: boolean description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. BreadthSnapshot: type: object properties: date: type: string pctAbove20d: type: number format: double description: |- Optional so a missing/failed Barchart reading serializes as JSON null instead of collapsing to 0, which would render identically to a real 0% reading (severe market dislocation with no S&P stocks above SMA). pctAbove50d: type: number format: double pctAbove200d: type: number format: double GetGoldIntelligenceRequest: type: object GetGoldIntelligenceResponse: type: object properties: goldPrice: type: number format: double goldChangePct: type: number format: double goldSparkline: type: array items: type: number format: double silverPrice: type: number format: double platinumPrice: type: number format: double palladiumPrice: type: number format: double goldSilverRatio: type: number format: double goldPlatinumPremiumPct: type: number format: double crossCurrencyPrices: type: array items: $ref: '#/components/schemas/GoldCrossCurrencyPrice' cot: $ref: '#/components/schemas/GoldCotPositioning' updatedAt: type: string unavailable: type: boolean description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. session: $ref: '#/components/schemas/GoldSessionRange' returns: $ref: '#/components/schemas/GoldReturns' range52w: $ref: '#/components/schemas/GoldRange52w' drivers: type: array items: $ref: '#/components/schemas/GoldDriver' etfFlows: $ref: '#/components/schemas/GoldEtfFlows' cbReserves: $ref: '#/components/schemas/GoldCbReserves' goldSparklineIntervalSeconds: type: integer format: int32 description: 'Width of each gold_sparkline bar in seconds: 300 for the intraday series, 86400 for daily closes.' goldSparklineStartAt: type: integer format: int64 description: |- Start of the first gold_sparkline bar in Unix epoch milliseconds. Later bars follow in trading order with closed periods left out, so only the first point's time is defined.. Warning: Values > 2^53 may lose precision in JavaScript GoldCrossCurrencyPrice: type: object properties: currency: type: string flag: type: string price: type: number format: double GoldCotPositioning: type: object properties: reportDate: type: string nextReleaseDate: type: string openInterest: type: string format: int64 managedMoney: $ref: '#/components/schemas/GoldCotCategory' producerSwap: $ref: '#/components/schemas/GoldCotCategory' GoldCotCategory: type: object properties: longPositions: type: string format: int64 shortPositions: type: string format: int64 netPct: type: number format: double oiSharePct: type: number format: double wowNetDelta: type: string format: int64 GoldSessionRange: type: object properties: dayHigh: type: number format: double dayLow: type: number format: double prevClose: type: number format: double GoldReturns: type: object properties: w1: type: number format: double m1: type: number format: double ytd: type: number format: double y1: type: number format: double GoldRange52w: type: object properties: hi: type: number format: double lo: type: number format: double positionPct: type: number format: double GoldDriver: type: object properties: symbol: type: string label: type: string value: type: number format: double changePct: type: number format: double correlation30d: type: number format: double GoldEtfFlows: type: object properties: asOfDate: type: string tonnes: type: number format: double aumUsd: type: number format: double nav: type: number format: double changeW1Tonnes: type: number format: double changeM1Tonnes: type: number format: double changeY1Tonnes: type: number format: double changeW1Pct: type: number format: double changeM1Pct: type: number format: double changeY1Pct: type: number format: double sparkline90d: type: array items: type: number format: double GoldCbReserves: type: object properties: asOfMonth: type: string totalTonnes: type: number format: double description: Measured only when value_is_ounces is true; otherwise a legacy zero placeholder. topHolders: type: array items: $ref: '#/components/schemas/GoldCbHolder' topBuyers12m: type: array items: $ref: '#/components/schemas/GoldCbMover' topSellers12m: type: array items: $ref: '#/components/schemas/GoldCbMover' indicator: type: string description: IMF IRFCL indicator used by the reserve snapshot. valueIsOunces: type: boolean description: |- True for ounce-based measurements. False for the USD fallback, where tonnes are placeholders and physical movers are unavailable. Absent if unknown. GoldCbHolder: type: object properties: iso3: type: string name: type: string tonnes: type: number format: double description: Measured only when value_is_ounces is true; otherwise a legacy zero placeholder. pctOfReserves: type: number format: double GoldCbMover: type: object properties: iso3: type: string name: type: string deltaTonnes12m: type: number format: double GetHyperliquidFlowRequest: type: object GetHyperliquidFlowResponse: type: object properties: ts: type: string format: int64 fetchedAt: type: string warmup: type: boolean assetCount: type: integer format: int32 assets: type: array items: $ref: '#/components/schemas/HyperliquidAssetFlow' unavailable: type: boolean description: |- True when the upstream or seed-backed variant is unavailable; empty payload fields are graceful degradation, not confirmed zero data. HyperliquidAssetFlow: type: object properties: symbol: type: string display: type: string assetClass: type: string group: type: string funding: type: string description: Raw metrics (nullable as strings to preserve precision; "" = unavailable) openInterest: type: string markPx: type: string oraclePx: type: string dayNotional: type: string fundingScore: type: number format: double description: Component scores 0-100 volumeScore: type: number format: double oiScore: type: number format: double basisScore: type: number format: double composite: type: number format: double sparkFunding: type: array items: type: number format: double description: Sparkline arrays (most recent last); up to 60 samples (5h @ 5min) sparkOi: type: array items: type: number format: double sparkScore: type: array items: type: number format: double warmup: type: boolean description: State flags stale: type: boolean staleSince: type: string format: int64 missingPolls: type: integer format: int32 alerts: type: array items: type: string