{"openapi":"3.1.0","info":{"title":"Centaur API","version":"2.0.0","description":"Public, read-only API for Centaur's data over REST with a companion MCP surface."},"servers":[{"url":"https://api.centaur.io/v2","description":"Centaur API v2"}],"externalDocs":{"description":"Canonical Centaur API documentation","url":"https://docs.centaur.io"},"tags":[{"name":"System","description":"Health and service metadata endpoints."},{"name":"Discovery","description":"Read-only trader and asset directory discovery endpoints."},{"name":"Events","description":"Historical trade-event reads with source, trader, asset, and position context."},{"name":"Messages","description":"Read-only access to source messages by message timestamp or Source Message ID."},{"name":"Channel Summaries","description":"Generated channel narrative summaries selected by Source Window overlap."},{"name":"Aggregate Summaries","description":"Generated aggregate narrative summaries selected by Aggregate Window overlap."},{"name":"Positions","description":"Read-only position history and open-position live state reads."},{"name":"Stats","description":"Read-only aggregate trader and asset stats."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key issued by Centaur.","x-default":"<api-key>"}},"schemas":{"EventsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange"]}},"required":["results","meta"]},"Event":{"type":"object","properties":{"id":{"type":"integer"},"type":{"$ref":"#/components/schemas/EventType"},"price":{"type":"number","nullable":true,"description":"Event price when extracted or assigned; null when unavailable."},"quoteSymbol":{"type":"string","nullable":true,"description":"Quote currency of the asset's preferred market (e.g. USDT, USDC, CAD), labelling the price fields. Resolved from the asset's current markets, not stored per trade. Null when the asset has no active market."},"timeOfEvent":{"type":"string","format":"date-time","description":"Timestamp used for event ordering and time filters."},"assumed":{"type":"boolean","description":"True when the system inferred this event from position progression rather than direct source text."},"retrospective":{"type":"boolean","description":"True when the source described the action after it happened."},"autoGenerated":{"type":"boolean","description":"True when the system generated this event, usually to close stale or superseded position state."},"positionId":{"type":"integer","description":"Related position ID. Use position reads to hydrate performance details."},"traderId":{"type":"integer","description":"Related trader ID. Use trader discovery for display metadata."},"assetId":{"type":"integer","description":"Related asset ID. Use asset discovery for display metadata."},"messageId":{"type":"string","nullable":true,"description":"Related Source Message ID when this event has source-message context."}},"required":["id","type","price","quoteSymbol","timeOfEvent","assumed","retrospective","autoGenerated","positionId","traderId","assetId","messageId"]},"EventType":{"type":"string","enum":["open","close","increase","decrease"]},"AppliedTimeRange":{"type":"object","properties":{"startTime":{"type":"string","nullable":true,"format":"date-time"},"endTime":{"type":"string","nullable":true,"format":"date-time"}},"required":["startTime","endTime"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/Error"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","error","requestId"]},"Error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"UNAUTHORIZED"},"message":{"type":"string","description":"Human-readable explanation for the failure.","example":"Unauthorized"},"details":{"nullable":true,"description":"Optional structured details for validation or input failures."}},"required":["code","message"]},"TraderDirection":{"type":"string","enum":["long","short"]},"MessagesResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange"]}},"required":["results","meta"]},"Message":{"type":"object","properties":{"traderId":{"type":"integer","description":"Assigned trader ID. Resolve identity with the trader directory."},"id":{"type":"string","description":"Stable opaque Source Message ID used for direct hydration with the `ids` query parameter."},"source":{"$ref":"#/components/schemas/SourceMessage"}},"required":["traderId","id","source"]},"SourceMessage":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SourcePlatform"},"identity":{"$ref":"#/components/schemas/SourceIdentity"},"preview":{"$ref":"#/components/schemas/SourcePreview"}},"required":["platform","identity","preview"],"description":"Source identity and message preview payload."},"SourcePlatform":{"type":"string","enum":["TELEGRAM","X"]},"SourceIdentity":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SourcePlatform"},"sourceIdentityId":{"type":"string","description":"Opaque platform-scoped source identity ID for the source account or channel."},"displayName":{"type":"string","nullable":true,"description":"Display name for the source account or channel when available."},"handle":{"type":"string","nullable":true,"description":"Public source handle when available."},"avatarUrl":{"type":"string","nullable":true,"description":"Source account or channel avatar URL when available."},"profileUrl":{"type":"string","nullable":true,"description":"Original source account or channel URL when available."},"audienceCount":{"type":"integer","nullable":true,"description":"Follower or subscriber count when available."}},"required":["platform","sourceIdentityId","displayName","handle","avatarUrl","profileUrl","audienceCount"]},"SourcePreview":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SourcePlatform"},"writtenAt":{"type":"string","format":"date-time","description":"Timestamp of the original source message."},"url":{"type":"string","nullable":true,"description":"Original source message URL when available."},"text":{"type":"string","nullable":true,"description":"Sanitized source-message text when available."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"},"description":"Source-message attachments available to this read surface."},"isEdited":{"type":"boolean","nullable":true,"description":"Whether the source message was edited when available."},"isReply":{"type":"boolean","nullable":true,"description":"Whether the source message is a reply when available."},"isQuote":{"type":"boolean","nullable":true,"description":"Whether the source message quotes another source item when available."},"isRepost":{"type":"boolean","nullable":true,"description":"Whether the source message reposts another source item when available."}},"required":["platform","writtenAt","url","text","attachments","isEdited","isReply","isQuote","isRepost"]},"Attachment":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"FeedResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"},"dataComputedAt":{"type":"string","format":"date-time","description":"UTC start time of the read that produced this feed page. Default first pages may reuse data for up to 10 minutes. serverTime remains the response time."}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange","dataComputedAt"]}},"required":["results","meta"]},"FeedItem":{"type":"object","properties":{"id":{"type":"string","description":"Opaque Source Message ID used as the group upsert key."},"writtenAt":{"type":"string","format":"date-time","description":"Source-message post time used for group ordering and time filters."},"source":{"$ref":"#/components/schemas/FeedSource"},"trader":{"$ref":"#/components/schemas/FeedTrader"},"events":{"type":"array","items":{"$ref":"#/components/schemas/FeedEvent"},"minItems":1}},"required":["id","writtenAt","source","trader","events"]},"FeedSource":{"type":"object","properties":{"platform":{"$ref":"#/components/schemas/SourcePlatform"},"url":{"type":"string","nullable":true,"description":"Original source message URL when available."},"text":{"type":"string","nullable":true,"description":"Sanitized source-message text when available."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"identity":{"$ref":"#/components/schemas/SourceIdentity"}},"required":["platform","url","text","attachments","identity"]},"FeedTrader":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}},"required":["id","name","slug","avatarUrl"]},"FeedEvent":{"type":"object","properties":{"id":{"type":"integer"},"type":{"$ref":"#/components/schemas/EventType"},"price":{"type":"number","nullable":true,"description":"Event price when extracted or assigned; null when unavailable."},"quoteSymbol":{"type":"string","nullable":true,"description":"Quote currency of the asset's preferred active market."},"timeOfEvent":{"type":"string","format":"date-time"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"assumed":{"type":"boolean","description":"True when the retained event was inferred, including lone inferred opens, increases, or decreases."},"retrospective":{"type":"boolean"},"positionId":{"type":"integer"},"traderId":{"type":"integer"},"assetId":{"type":"integer"},"asset":{"$ref":"#/components/schemas/AssetSummary"}},"required":["id","type","price","quoteSymbol","timeOfEvent","direction","assumed","retrospective","positionId","traderId","assetId","asset"]},"AssetSummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"symbol":{"type":"string"},"logoUrl":{"type":"string","nullable":true}},"required":["id","name","symbol","logoUrl"]},"ChannelSummariesResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ChannelSummary"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange"]}},"required":["results","meta"]},"ChannelSummary":{"type":"object","properties":{"id":{"type":"string"},"traderId":{"type":"integer","description":"Stable trader ID for correlating Generated Channel Narrative Summaries from the same trader over time."},"windowStart":{"type":"string","format":"date-time","description":"Inclusive UTC start of the source window."},"windowEnd":{"type":"string","format":"date-time","description":"Exclusive UTC end of the source window."},"generatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["safe","low_signal"]},"overview":{"type":"string"},"keyInsights":{"type":"array","items":{"type":"string"},"maxItems":3},"marketBias":{"type":"string","enum":["bullish","bearish","mixed","neutral","unclear"]},"mentionedAssets":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string","nullable":true},"stance":{"type":"string","enum":["bullish","bearish","mixed","neutral","unclear"]},"confidence":{"type":"string","enum":["low","medium","high"]}},"required":["symbol","name","stance","confidence"]},"maxItems":5}},"required":["id","traderId","windowStart","windowEnd","generatedAt","status","overview","keyInsights","marketBias","mentionedAssets"]},"AggregateSummariesResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AggregateSummary"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange"]}},"required":["results","meta"]},"AggregateSummary":{"type":"object","properties":{"id":{"type":"string"},"windowStart":{"type":"string","format":"date-time","description":"Inclusive UTC start of the aggregate window."},"windowEnd":{"type":"string","format":"date-time","description":"Exclusive UTC end of the aggregate window."},"generatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["safe","low_signal"]},"headline":{"type":"string"},"overview":{"type":"string"},"dominantNarratives":{"type":"array","items":{"type":"string"},"maxItems":5},"contrarianTheses":{"type":"array","items":{"type":"string"},"maxItems":5},"marketDrivers":{"type":"array","items":{"type":"string"},"maxItems":8},"assetSentiment":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string","nullable":true},"discussionRank":{"type":"integer"},"sentiment":{"type":"string","enum":["bullish","bearish","mixed","neutral","unclear"]},"intensity":{"type":"string","enum":["low","medium","high"]},"thesis":{"type":"string"},"drivers":{"type":"array","items":{"type":"string"}},"contrarianAngle":{"type":"string","nullable":true},"confidence":{"type":"string","enum":["low","medium","high"]}},"required":["symbol","name","discussionRank","sentiment","intensity","thesis","drivers","contrarianAngle","confidence"]},"maxItems":8},"risks":{"type":"array","items":{"type":"string"},"maxItems":5},"coverage":{"type":"object","properties":{"eligibleSourceCount":{"type":"integer"},"activeSourceCount":{"type":"integer"},"messageCount":{"type":"integer"},"attachmentCount":{"type":"integer"}},"required":["eligibleSourceCount","activeSourceCount","messageCount","attachmentCount"]}},"required":["id","windowStart","windowEnd","generatedAt","status","headline","overview","dominantNarratives","contrarianTheses","marketDrivers","assetSentiment","risks","coverage"]},"PositionsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","serverTime","appliedTimeRange"]}},"required":["results","meta"]},"Position":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"openAt":{"type":"string","format":"date-time","description":"Position open timestamp used for position history time filters."},"openPrice":{"type":"number","nullable":true,"description":"Entry/open price when available."},"quoteSymbol":{"type":"string","nullable":true,"description":"Quote currency of the asset's preferred market (e.g. USDT, USDC, CAD), labelling the price fields. Resolved from the asset's current markets, not stored per trade. Null when the asset has no active market."},"timeBasedPerformances":{"$ref":"#/components/schemas/PositionTimeBasedPerformances"},"traderId":{"type":"integer","description":"Related trader ID. Use trader discovery for display metadata."},"assetId":{"type":"integer","description":"Related asset ID. Use asset discovery for display metadata."}},"required":["id","direction","openAt","openPrice","quoteSymbol","timeBasedPerformances","traderId","assetId"]},"PositionTimeBasedPerformances":{"type":"object","properties":{"1D":{"anyOf":[{"$ref":"#/components/schemas/PositionTimeBasedPerformance"},{"nullable":true}]},"7D":{"anyOf":[{"$ref":"#/components/schemas/PositionTimeBasedPerformance"},{"nullable":true}]},"30D":{"anyOf":[{"$ref":"#/components/schemas/PositionTimeBasedPerformance"},{"nullable":true}]}},"required":["1D","7D","30D"],"description":"Fixed-window 1D, 7D, and 30D performance values. A window can be null or unavailable by status."},"PositionTimeBasedPerformance":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},"status":{"$ref":"#/components/schemas/TimeBasedPerformanceStatus"},"returnPercentage":{"type":"number","nullable":true,"description":"Return at the fixed time-based performance window, or null when unavailable."}},"required":["window","status","returnPercentage"]},"TimeBasedPerformanceWindow":{"type":"string","enum":["1D","7D","30D"]},"TimeBasedPerformanceStatus":{"type":"string","enum":["ready","too_young","missing_forward_price","missing_entry_price","zero_entry_price","calculation_error"],"description":"`ready` means `returnPercentage` is populated; other statuses explain why the fixed-window return is unavailable."},"OpenPositionsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/OpenPosition"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["hasMore","nextCursor","serverTime"]}},"required":["results","meta"]},"OpenPosition":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"openAt":{"type":"string","format":"date-time","description":"Position open timestamp."},"openPrice":{"type":"number","nullable":true,"description":"Entry/open price when available."},"quoteSymbol":{"type":"string","nullable":true,"description":"Quote currency of the asset's preferred market (e.g. USDT, USDC, CAD), labelling the price fields. Resolved from the asset's current markets, not stored per trade. Null when the asset has no active market."},"currentPrice":{"type":"number","nullable":true,"description":"Best-effort current mark price when pricing is available. No separate priceAsOf field is exposed."},"currentReturnPercentage":{"type":"number","nullable":true,"description":"Live mark-to-market return for the open position when current price and entry price are available."},"traderId":{"type":"integer","description":"Related trader ID. Use trader discovery for display metadata."},"assetId":{"type":"integer","description":"Related asset ID. Use asset discovery for display metadata."}},"required":["id","direction","openAt","openPrice","quoteSymbol","currentPrice","currentReturnPercentage","traderId","assetId"]},"AssetsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AssetDiscovery"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["hasMore","nextCursor","serverTime"]}},"required":["results","meta"]},"AssetDiscovery":{"allOf":[{"$ref":"#/components/schemas/AssetSummary"},{"type":"object","properties":{"assetClass":{"type":"string","enum":["crypto","equities","commodities","fx","other"],"description":"Raw asset class. Unknown or missing classes resolve to other."},"resolvedAssetClass":{"type":"string","enum":["crypto","stocks","indices","commodities","fx","other"],"description":"Asset class with equities split into stocks and indices, matching the web app. Unknown or missing classes resolve to other."}},"required":["assetClass","resolvedAssetClass"]}]},"TraderStatsResponseData":{"type":"object","properties":{"filtersApplied":{"type":"object","properties":{"assetIds":{"type":"array","items":{"type":"integer"}},"sourcePlatforms":{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}},"direction":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"nullable":true}]},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["assetIds","sourcePlatforms","direction","appliedTimeRange"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/TraderStats"}},"meta":{"type":"object","properties":{"requestedTraderIds":{"type":"array","items":{"type":"integer"}},"missingTraderIds":{"type":"array","items":{"type":"integer"}},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["requestedTraderIds","missingTraderIds","serverTime"]}},"required":["filtersApplied","results","meta"]},"TraderStats":{"type":"object","properties":{"traderId":{"type":"integer"},"source":{"allOf":[{"$ref":"#/components/schemas/SourceIdentity"},{"nullable":true}]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TraderTag"},"description":"Editorial trader tags grouped into categories, e.g. thematic macro themes the trader expresses. Empty when the trader has none."},"summary":{"type":"object","properties":{"timeBasedPerformances":{"type":"object","properties":{"1D":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},"averageReturnPercentage":{"type":"number","nullable":true},"medianReturnPercentage":{"type":"number","nullable":true},"winRatePercentage":{"type":"number","nullable":true},"sharpeRatio":{"type":"number","nullable":true},"positionsCount":{"type":"integer"},"coverage":{"type":"object","properties":{"sampledPositionsCount":{"type":"integer"},"scoredPositionsCount":{"type":"integer"},"ratio":{"type":"number","minimum":0,"maximum":1}},"required":["sampledPositionsCount","scoredPositionsCount","ratio"]}},"required":["window","averageReturnPercentage","medianReturnPercentage","winRatePercentage","sharpeRatio","positionsCount","coverage"]},"7D":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},"averageReturnPercentage":{"type":"number","nullable":true},"medianReturnPercentage":{"type":"number","nullable":true},"winRatePercentage":{"type":"number","nullable":true},"sharpeRatio":{"type":"number","nullable":true},"positionsCount":{"type":"integer"},"coverage":{"type":"object","properties":{"sampledPositionsCount":{"type":"integer"},"scoredPositionsCount":{"type":"integer"},"ratio":{"type":"number","minimum":0,"maximum":1}},"required":["sampledPositionsCount","scoredPositionsCount","ratio"]}},"required":["window","averageReturnPercentage","medianReturnPercentage","winRatePercentage","sharpeRatio","positionsCount","coverage"]},"30D":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},"averageReturnPercentage":{"type":"number","nullable":true},"medianReturnPercentage":{"type":"number","nullable":true},"winRatePercentage":{"type":"number","nullable":true},"sharpeRatio":{"type":"number","nullable":true},"positionsCount":{"type":"integer"},"coverage":{"type":"object","properties":{"sampledPositionsCount":{"type":"integer"},"scoredPositionsCount":{"type":"integer"},"ratio":{"type":"number","minimum":0,"maximum":1}},"required":["sampledPositionsCount","scoredPositionsCount","ratio"]}},"required":["window","averageReturnPercentage","medianReturnPercentage","winRatePercentage","sharpeRatio","positionsCount","coverage"]}},"required":["1D","7D","30D"]},"assetFocus":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"integer"},"positionsCount":{"type":"integer"},"sharePercentage":{"type":"number"}},"required":["assetId","positionsCount","sharePercentage"]}},"directionBias":{"$ref":"#/components/schemas/DirectionBias"}},"required":["timeBasedPerformances","assetFocus","directionBias"]}},"required":["traderId","source","tags","summary"]},"TraderTag":{"type":"object","properties":{"category":{"type":"string","description":"Tag category, e.g. `thematic`. Open set; new categories may be added over time."},"name":{"type":"string","description":"Tag name within the category, lowercase, e.g. `ai capex buildout`."}},"required":["category","name"]},"DirectionBias":{"type":"object","properties":{"label":{"type":"string","enum":["long","short","neutral"]},"longCount":{"type":"integer"},"shortCount":{"type":"integer"},"longPercentage":{"type":"number","nullable":true},"shortPercentage":{"type":"number","nullable":true}},"required":["label","longCount","shortCount","longPercentage","shortPercentage"]},"AssetStatsResponseData":{"type":"object","properties":{"filtersApplied":{"type":"object","properties":{"traderIds":{"type":"array","items":{"type":"integer"}},"direction":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"nullable":true}]},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["traderIds","direction","appliedTimeRange"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/AssetStats"}},"meta":{"type":"object","properties":{"requestedAssetIds":{"type":"array","items":{"type":"integer"}},"missingAssetIds":{"type":"array","items":{"type":"integer"}},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["requestedAssetIds","missingAssetIds","serverTime"]}},"required":["filtersApplied","results","meta"]},"AssetStats":{"type":"object","properties":{"assetId":{"type":"integer"},"summary":{"type":"object","properties":{"marketPositioning":{"$ref":"#/components/schemas/DirectionBias"},"topTraderIds":{"type":"object","properties":{"long":{"type":"array","items":{"type":"integer"}},"short":{"type":"array","items":{"type":"integer"}}},"required":["long","short"]}},"required":["marketPositioning","topTraderIds"]}},"required":["assetId","summary"]},"TraderRankingsResponseData":{"type":"object","properties":{"filtersApplied":{"type":"object","properties":{"metric":{"$ref":"#/components/schemas/TraderRankingMetric"},"assetIds":{"type":"array","items":{"type":"integer"}},"direction":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"nullable":true}]},"timeBasedPerformanceWindow":{"allOf":[{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},{"nullable":true}]},"minPositions":{"type":"integer","nullable":true},"windowEvaluability":{"type":"string","nullable":true,"enum":["partial","full",null]},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["metric","assetIds","direction","timeBasedPerformanceWindow","minPositions","windowEvaluability","appliedTimeRange"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/TraderRanking"}},"meta":{"type":"object","properties":{"totalCandidates":{"type":"integer","description":"Number of traders that qualified for the ranking before the limit was applied."},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["totalCandidates","serverTime"]}},"required":["filtersApplied","results","meta"]},"TraderRankingMetric":{"type":"string","enum":["event_count","position_count","win_rate","avg_return","median_return","sharpe_ratio"]},"TraderRanking":{"type":"object","properties":{"traderId":{"type":"integer","description":"Related trader ID. Use trader discovery for display metadata."},"rank":{"type":"integer","description":"1-based rank position for the applied metric."},"metricValue":{"type":"number","nullable":true,"description":"Value of the applied ranking metric for this trader."},"eventCount":{"type":"integer","description":"Events for this trader inside the applied time range."},"positionCount":{"type":"integer","description":"Positions opened by this trader inside the applied time range."},"directionBias":{"$ref":"#/components/schemas/DirectionBias"},"timeBasedPerformance":{"$ref":"#/components/schemas/TraderRankingTimeBasedPerformance"}},"required":["traderId","rank","metricValue","eventCount","positionCount","directionBias","timeBasedPerformance"]},"TraderRankingTimeBasedPerformance":{"type":"object","nullable":true,"properties":{"window":{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},"averageReturnPercentage":{"type":"number","nullable":true},"medianReturnPercentage":{"type":"number","nullable":true},"winRatePercentage":{"type":"number","nullable":true},"sharpeRatio":{"type":"number","nullable":true},"positionsCount":{"type":"integer","description":"Number of evaluated positions in the applied window. Qualify thin samples when presenting results."},"coverage":{"type":"object","properties":{"sampledPositionsCount":{"type":"integer","description":"Positions opened inside the resolved sample."},"scoredPositionsCount":{"type":"integer","description":"Sampled positions with a usable result for this window."},"ratio":{"type":"number","minimum":0,"maximum":1,"description":"Scored positions divided by sampled positions, from 0 to 1."}},"required":["sampledPositionsCount","scoredPositionsCount","ratio"]}},"required":["window","averageReturnPercentage","medianReturnPercentage","winRatePercentage","sharpeRatio","positionsCount","coverage"],"description":"Time-based performance summary for the applied window. Present for performance metrics, null for activity metrics."},"ActivitySummariesResponseData":{"type":"object","properties":{"filtersApplied":{"type":"object","properties":{"groupBy":{"$ref":"#/components/schemas/ActivitySummaryGroupBy"},"interval":{"$ref":"#/components/schemas/ActivitySummaryInterval"},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"traderIds":{"type":"array","items":{"type":"integer"}},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["groupBy","interval","eventTypes","traderIds","appliedTimeRange"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/ActivitySummary"}},"meta":{"type":"object","properties":{"totalMessages":{"type":"integer","description":"Total messages across all groups, not only the returned top groups."},"totalEvents":{"type":"integer","description":"Total events across all groups, not only the returned top groups."},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["totalMessages","totalEvents","serverTime"]}},"required":["filtersApplied","results","meta"]},"ActivitySummaryGroupBy":{"type":"string","enum":["trader","none"]},"ActivitySummaryInterval":{"type":"string","enum":["hour","day","week"]},"ActivitySummary":{"type":"object","properties":{"traderId":{"type":"integer","nullable":true,"description":"Related trader ID for `groupBy=trader`, null for the overall `groupBy=none` group."},"messageCount":{"type":"integer","description":"Total source messages for this group inside the applied time range."},"eventCount":{"type":"integer","description":"Total events for this group inside the applied time range."},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/ActivitySummaryBucket"},"description":"Per-interval counts ordered by bucket start. Buckets with no activity are omitted."}},"required":["traderId","messageCount","eventCount","buckets"]},"ActivitySummaryBucket":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Inclusive UTC bucket start, truncated to the applied interval."},"end":{"type":"string","format":"date-time","description":"Exclusive UTC bucket end."},"messageCount":{"type":"integer"},"eventCount":{"type":"integer"}},"required":["start","end","messageCount","eventCount"]},"TraderDirectoryResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TraderDirectoryEntry"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["hasMore","nextCursor","serverTime"]}},"required":["results","meta"]},"TraderDirectoryEntry":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"source":{"allOf":[{"$ref":"#/components/schemas/SourceIdentity"},{"nullable":true}]}},"required":["id","name","slug","avatarUrl","source"]},"TraderActivityResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"traderId":{"type":"integer"},"positionCount":{"type":"integer"}},"required":["traderId","positionCount"]}},"filtersApplied":{"type":"object","properties":{"search":{"type":"string","nullable":true},"traderIds":{"type":"array","items":{"type":"integer"}},"assetIds":{"type":"array","items":{"type":"integer"}},"sourcePlatforms":{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}},"minPositionCount":{"type":"integer"},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["search","traderIds","assetIds","sourcePlatforms","minPositionCount","appliedTimeRange"]},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"serverTime":{"type":"string","format":"date-time","description":"Server UTC time when this response was produced (ISO-8601). Anchor relative-time phrases such as \"today\" or \"this week\" on this value rather than on a cached one."}},"required":["hasMore","nextCursor","serverTime"]}},"required":["results","filtersApplied","meta"]},"HealthResponseData":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}},"parameters":{}},"paths":{"/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List trading events","description":"Returns source-backed and classified trading events. Event rows can include assumed, retrospective, and auto-generated flags; user-facing clients should usually hide assumed and auto-generated system events.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/EventType"}}],"description":"Filter to specific event types: `open`, `close`, `increase`, or `decrease`."},"required":false,"description":"Filter to specific event types: `open`, `close`, `increase`, or `decrease`.","name":"types","in":"query"}],"responses":{"200":{"description":"Paginated list of public trading events with compact entity references","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/EventsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/messages":{"get":{"tags":["Messages"],"operationId":"listMessages","summary":"List source message feed","description":"Returns eligible source messages by source platform, message timestamp, or direct Source Message ID hydration. Trader IDs select messages independently of signal visibility. Asset, direction, and event-type filters are not supported.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter messages by their assigned trader IDs, independently of signal visibility."},"required":false,"description":"Filter messages by their assigned trader IDs, independently of signal visibility.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific opaque Source Message IDs returned by message `id` or event `messageId`."},"required":false,"description":"Filter to specific opaque Source Message IDs returned by message `id` or event `messageId`.","name":"ids","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}}],"description":"Filter to source messages whose source platform is `TELEGRAM` or `X`."},"required":false,"description":"Filter to source messages whose source platform is `TELEGRAM` or `X`.","name":"sourcePlatforms","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound on message timestamp."},"required":false,"description":"Inclusive ISO-8601 lower time bound on message timestamp.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound on message timestamp."},"required":false,"description":"Inclusive ISO-8601 upper time bound on message timestamp.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated list of source messages","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MessagesResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/feed":{"get":{"tags":["Feed"],"operationId":"listFeed","summary":"List the curated partner feed","description":"Returns presentation-ready source-message groups ordered by message post time. Use cursor for scroll-back pagination or since for ingestion-watermark change polling with whole-group upsert semantics.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound on source-message post time, clamped to the rolling seven-day feed window."},"required":false,"description":"Inclusive ISO-8601 lower time bound on source-message post time, clamped to the rolling seven-day feed window.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound on source-message post time. Defaults to the request time."},"required":false,"description":"Inclusive ISO-8601 upper time bound on source-message post time. Defaults to the request time.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of source-message groups to return. Defaults to 20, maximum 100."},"required":false,"description":"Maximum number of source-message groups to return. Defaults to 20, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Scroll-back cursor from `meta.nextCursor`; mutually exclusive with `since`."},"required":false,"description":"Scroll-back cursor from `meta.nextCursor`; mutually exclusive with `since`.","name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Change-feed token from `meta.nextCursor`; returns groups changed after its ingestion watermark and is mutually exclusive with `cursor`."},"required":false,"description":"Change-feed token from `meta.nextCursor`; returns groups changed after its ingestion watermark and is mutually exclusive with `cursor`.","name":"since","in":"query"}],"responses":{"200":{"description":"Paginated source-message groups with curated trading events","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/FeedResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"example":{"success":false,"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/channel-summaries":{"get":{"tags":["Channel Summaries"],"operationId":"listChannelSummaries","summary":"List generated channel narrative summaries","description":"Returns generated channel narrative summaries selected by Source Window overlap. Results expose traderId for continuity but not channel identity or raw source material.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"ISO-8601 lower bound for Source Window overlap. A Source Window must end after this timestamp."},"required":false,"description":"ISO-8601 lower bound for Source Window overlap. A Source Window must end after this timestamp.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO-8601 upper bound for Source Window overlap. A Source Window must start before this timestamp."},"required":false,"description":"ISO-8601 upper bound for Source Window overlap. A Source Window must start before this timestamp.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string"}],"description":"Include low-signal generated summaries. Defaults to false, returning only safe summaries."},"required":false,"description":"Include low-signal generated summaries. Defaults to false, returning only safe summaries.","name":"includeLowSignal","in":"query"}],"responses":{"200":{"description":"Paginated list of generated channel narrative summaries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ChannelSummariesResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/aggregate-summaries":{"get":{"tags":["Aggregate Summaries"],"operationId":"listAggregateSummaries","summary":"List generated aggregate narrative summaries","description":"Returns generated aggregate narrative summaries selected by Aggregate Window overlap. Results expose coverage counts rather than source trader or channel identities.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"ISO-8601 lower bound for Aggregate Window overlap. An Aggregate Window must end after this timestamp."},"required":false,"description":"ISO-8601 lower bound for Aggregate Window overlap. An Aggregate Window must end after this timestamp.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO-8601 upper bound for Aggregate Window overlap. An Aggregate Window must start before this timestamp."},"required":false,"description":"ISO-8601 upper bound for Aggregate Window overlap. An Aggregate Window must start before this timestamp.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string"}],"description":"Include low-signal Generated Aggregate Narrative Summaries. Defaults to false, returning only safe summaries."},"required":false,"description":"Include low-signal Generated Aggregate Narrative Summaries. Defaults to false, returning only safe summaries.","name":"includeLowSignal","in":"query"}],"responses":{"200":{"description":"Paginated list of generated aggregate narrative summaries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AggregateSummariesResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/positions":{"get":{"tags":["Positions"],"operationId":"listPositions","summary":"List positions","description":"Returns open and closed position history by position open time, including 1D, 7D, and 30D time-based performance where available.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific position IDs."},"required":false,"description":"Filter to specific position IDs.","name":"positionIds","in":"query"}],"responses":{"200":{"description":"Paginated position history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PositionsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/positions/open":{"get":{"tags":["Positions"],"operationId":"listOpenPositions","summary":"List open positions","description":"Returns currently open positions with best-effort current marks and live mark-to-market return when pricing is available.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated currently open positions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/OpenPositionsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/assets":{"get":{"tags":["Discovery"],"operationId":"listAssets","summary":"List assets","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string","enum":["crypto","stocks","indices","commodities","fx"]}}],"description":"Filter by crypto, stocks, indices, commodities, or fx. Comma-separated values or an array match any selected class. Omit or pass an empty value for all classes, including other."},"required":false,"description":"Filter by crypto, stocks, indices, commodities, or fx. Comma-separated values or an array match any selected class. Omit or pass an empty value for all classes, including other.","name":"assetClass","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Case-insensitive partial match against asset name or symbol."},"required":false,"description":"Case-insensitive partial match against asset name or symbol.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to assets with eligible positions from specific trader IDs."},"required":false,"description":"Filter to assets with eligible positions from specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated list of assets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AssetsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/traders/stats":{"get":{"tags":["Stats"],"operationId":"listTraderStats","summary":"List trader stats","description":"Returns aggregate trader stats for explicit trader IDs, including 1D, 7D, and 30D time-based performance, editorial trader tags, and missing/inaccessible IDs in metadata.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Trader IDs to fetch stats for. Maximum 200 IDs."},"required":true,"description":"Trader IDs to fetch stats for. Maximum 200 IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}}],"description":"Filter to traders whose source platform is `TELEGRAM` or `X`."},"required":false,"description":"Filter to traders whose source platform is `TELEGRAM` or `X`.","name":"sourcePlatforms","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"description":"Filter to a single direction: `long` or `short`."}]},"required":false,"description":"Filter to a single direction: `long` or `short`.","name":"direction","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"}],"responses":{"200":{"description":"Trader stats collection for requested trader IDs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TraderStatsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/assets/stats":{"get":{"tags":["Stats"],"operationId":"listAssetStats","summary":"List asset stats","description":"Returns aggregate asset stats for explicit asset IDs, including market positioning and top trader ID references with missing/inaccessible IDs in metadata.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Asset IDs to fetch stats for. Maximum 200 IDs."},"required":true,"description":"Asset IDs to fetch stats for. Maximum 200 IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"description":"Filter to a single direction: `long` or `short`."}]},"required":false,"description":"Filter to a single direction: `long` or `short`.","name":"direction","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"}],"responses":{"200":{"description":"Asset stats collection for requested asset IDs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AssetStatsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/traders/rankings":{"get":{"tags":["Rankings"],"operationId":"listTraderRankings","summary":"Rank traders","description":"Ranks traders across the platform by activity or performance over an explicit UTC time window, without requiring trader IDs. Returns a small bounded result ordered by the applied metric. Use this instead of paging raw events or messages for \"most active\" or \"best performing\" questions.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderRankingMetric"},{"description":"Ranking metric. Activity metrics: `event_count` (default) and `position_count`. Performance metrics: `win_rate`, `avg_return`, `median_return`, and `sharpe_ratio`."}]},"required":false,"description":"Ranking metric. Activity metrics: `event_count` (default) and `position_count`. Performance metrics: `win_rate`, `avg_return`, `median_return`, and `sharpe_ratio`.","name":"metric","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Restrict the ranking to traders active in specific asset IDs."},"required":false,"description":"Restrict the ranking to traders active in specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"description":"Filter to a single direction: `long` or `short`."}]},"required":false,"description":"Filter to a single direction: `long` or `short`.","name":"direction","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TimeBasedPerformanceWindow"},{"description":"Time-based performance evaluation window for performance metrics. Defaults to `30D`. Ignored for activity metrics. Invalid sample and evaluation combinations return HTTP 422 with valid retry alternatives."}]},"required":false,"description":"Time-based performance evaluation window for performance metrics. Defaults to `30D`. Ignored for activity metrics. Invalid sample and evaluation combinations return HTTP 422 with valid retry alternatives.","name":"timeBasedPerformanceWindow","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Minimum evaluated positions required for performance-metric rankings. Defaults to 3; pass 0 to include all traders. Ignored for activity metrics."},"required":false,"description":"Minimum evaluated positions required for performance-metric rankings. Defaults to 3; pass 0 to include all traders. Ignored for activity metrics.","name":"minPositions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound on position open time. Defaults to January 1 at 00:00:00 UTC in the applied endTime year."},"required":false,"description":"Inclusive ISO-8601 lower time bound on position open time. Defaults to January 1 at 00:00:00 UTC in the applied endTime year.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound. Defaults to the current server time."},"required":false,"description":"Inclusive ISO-8601 upper time bound. Defaults to the current server time.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"description":"Maximum number of ranked traders to return. Defaults to 10, maximum 50."},"required":false,"description":"Maximum number of ranked traders to return. Defaults to 10, maximum 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Bounded trader ranking for the applied metric and time window","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TraderRankingsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error, including performance-metric windows whose startTime is too recent for the evaluation window to have elapsed","content":{"application/json":{"example":{"success":false,"error":{"code":"PERFORMANCE_WINDOW_NOT_ELAPSED","message":"No position opened in the resolved sample can have a completed 30D time-based evaluation yet. Retry with one of the returned alternatives.","details":{"requested":{"startTime":"2026-08-23T00:00:00.000Z","endTime":"2026-08-30T00:00:00.000Z","timeBasedPerformanceWindow":"30D"},"resolved":{"startTime":"2026-08-23T00:00:00.000Z","endTime":"2026-08-30T00:00:00.000Z","timeBasedPerformanceWindow":"30D"},"alternatives":[{"strategy":"preserve_sample","startTime":"2026-08-23T00:00:00.000Z","endTime":"2026-08-30T00:00:00.000Z","timeBasedPerformanceWindow":"1D"},{"strategy":"preserve_evaluation","startTime":"2026-07-24T00:00:00.000Z","endTime":"2026-08-30T00:00:00.000Z","timeBasedPerformanceWindow":"30D"}]}},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/activity-summaries":{"get":{"tags":["Rankings"],"operationId":"listActivitySummaries","summary":"Summarize message and event activity","description":"Returns deterministic message and event counts over an explicit UTC time window, grouped by trader or overall and bucketed by a fixed interval. An Activity Summary is evidence-grade for counts, volumes, and trends; it is not a generated narrative summary. Use this instead of paging raw messages or events to count or trend activity.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/ActivitySummaryGroupBy"},{"description":"Group counts by `trader` (default) or return one overall group with `none`."}]},"required":false,"description":"Group counts by `trader` (default) or return one overall group with `none`.","name":"groupBy","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/ActivitySummaryInterval"},{"description":"Bucket interval: `hour`, `day` (default), or `week`. The window/interval combination is rejected when it would produce more than 168 buckets per group."}]},"required":false,"description":"Bucket interval: `hour`, `day` (default), or `week`. The window/interval combination is rejected when it would produce more than 168 buckets per group.","name":"interval","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/EventType"}}],"description":"Filter event counts to specific event types: `open`, `close`, `increase`, or `decrease`."},"required":false,"description":"Filter event counts to specific event types: `open`, `close`, `increase`, or `decrease`.","name":"eventTypes","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound. Defaults to 7 days before the applied endTime."},"required":false,"description":"Inclusive ISO-8601 lower time bound. Defaults to 7 days before the applied endTime.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound. Defaults to the current server time."},"required":false,"description":"Inclusive ISO-8601 upper time bound. Defaults to the current server time.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"description":"Maximum number of groups to return, ordered by combined activity. Defaults to 10, maximum 50."},"required":false,"description":"Maximum number of groups to return, ordered by combined activity. Defaults to 10, maximum 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Bounded activity counts per group with per-interval buckets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ActivitySummariesResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error, including window/interval combinations above the bucket limit","content":{"application/json":{"example":{"success":false,"error":{"code":"BUCKET_LIMIT_EXCEEDED","message":"The requested window would produce too many buckets per group. Widen the interval or narrow the startTime/endTime window."},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/traders":{"get":{"tags":["Discovery"],"operationId":"listTraderDirectory","summary":"List trader identities","description":"Find permitted trader identities independently of trading activity. Requires directory.read. Either message or signal visibility must permit the caller. Does not grant access to content.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Case-insensitive match against trader name, slug, source display name, handle, or profile URL."},"required":false,"description":"Case-insensitive match against trader name, slug, source display name, handle, or profile URL.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}}],"description":"Filter to traders whose source platform is `TELEGRAM` or `X`."},"required":false,"description":"Filter to traders whose source platform is `TELEGRAM` or `X`.","name":"sourcePlatforms","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated trader identities","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TraderDirectoryResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/traders/activity":{"get":{"tags":["Discovery"],"operationId":"listTraderActivity","summary":"List trader activity","description":"Select traders by eligible position count, asset, source platform, and optional position-open time. Requires stats.read and signal visibility. Resolve returned trader IDs through /v2/traders.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Case-insensitive partial match against trader name or slug."},"required":false,"description":"Case-insensitive partial match against trader name or slug.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to traders with eligible positions on specific asset IDs."},"required":false,"description":"Filter to traders with eligible positions on specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/SourcePlatform"}}],"description":"Filter to traders whose source platform is `TELEGRAM` or `X`."},"required":false,"description":"Filter to traders whose source platform is `TELEGRAM` or `X`.","name":"sourcePlatforms","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower bound on position open time for positionCount. Unbounded when omitted."},"required":false,"description":"Inclusive ISO-8601 lower bound on position open time for positionCount. Unbounded when omitted.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper bound on position open time for positionCount. Unbounded when omitted."},"required":false,"description":"Inclusive ISO-8601 upper bound on position open time for positionCount. Unbounded when omitted.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":0,"default":3,"description":"Minimum eligible position count after asset and position-open time filters. Defaults to 3; pass 0 to include zero-position traders."},"required":false,"description":"Minimum eligible position count after asset and position-open time filters. Defaults to 3; pass 0 to include zero-position traders.","name":"minPositionCount","in":"query"}],"responses":{"200":{"description":"Paginated trader position counts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TraderActivityResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Authentication service temporarily unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying authentication","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"example":{"success":false,"error":{"code":"AUTHENTICATION_UNAVAILABLE","message":"Authentication is temporarily unavailable"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/healthz":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Get service health","description":"Returns the current service health status.","responses":{"200":{"description":"Service health","content":{"application/json":{"example":{"success":true,"data":{"status":"ok"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"},"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/HealthResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}}}},"servers":[{"url":"https://api.centaur.io","description":"Service root"}]}}}