Capability map
Observable behavior across reads
- Operations are scope-gated. A key may work on some endpoint families and return
403on others. - Historical list reads and stats responses echo the applied bounds back to you after server-side clamping.
- Some rows may be omitted because they are deleted, tied to ineligible connected entities, or outside the current access policy. Omitted rows do not produce placeholder warnings.
- Cursor pagination always reflects the current eligible result set, not a frozen snapshot.
- Generated narrative summaries describe market narratives for their Source Window or Aggregate Window. They are not evidence for exact trade counts, public activity rankings, or current open-position skew.
- Open-position reads expose best-effort current marks when pricing is available. They do not currently expose a separate
priceAsOffield.
Example: trader discovery
tradeCount plus one nested source identity for the trader’s source platform, with platform, handle, display name, profile URL, avatar URL, and follower/subscriber count when available. Use sourcePlatforms=TELEGRAM, sourcePlatforms=X, or a comma-separated list to filter discovery before calling stats or detail reads. Use minTrades to require a minimum eligible visible position count; it defaults to 3, and minTrades=0 returns the full visible directory. startTime and endTime scope discovery tradeCount and minTrades by position open time. Trader stats rows expose the same source shape and accept the same sourcePlatforms filter.
Example: asset discovery
Example: messages
GET /api/v1/messages returns eligible source messages as a feed. Pass sourcePlatforms=TELEGRAM, sourcePlatforms=X, or a comma-separated list to filter by source platform. Pass ids to hydrate opaque Source Message IDs returned by message rows or event messageId references. Message rows do not expose traderId; use event messageId references or source-message IDs when you need to connect messages to event rows.
Each message row has id as the stable Source Message ID and a nested source payload. source.identity describes the source account or channel, including platform, handle, display name, profile URL, avatar URL, and follower/subscriber count when available. source.preview contains the message timestamp, original source URL, sanitized text, attachments, and platform-specific flags such as reply, quote, repost, or edit state when available.
Example: partner feed
cursor for older pages and since for ingestion-watermark change polling. A group returned by since is a whole-group upsert, so replace the prior group by id. See the Partner Feed guide for polling and curation rules.
Example: channel summaries
traderId, the source window, overview, market bias, capped key insights, capped mentioned assets, and pagination metadata. The traderId lets clients connect summaries from the same trader over time, but this read does not accept trader or Telegram channel filters. The default response includes only substantive safe summaries; pass includeLowSignal=true to include low-signal windows. This read supports a maximum limit of 200.
startTime and endTime select summaries whose Source Windows overlap the requested interval. For daily reads, use UTC day bounds such as 2026-03-01T00:00:00.000Z through 2026-03-02T00:00:00.000Z.
Channel summaries return a concise narrative shape without trader metadata, channel identity, raw source material, verbose rationales, or generator safety metadata.
Example: aggregate summaries
safe summaries; pass includeLowSignal=true to include low-signal windows. This read supports a maximum limit of 200.
startTime and endTime select summaries whose Aggregate Windows overlap the requested interval. Public responses expose coverage counts only, not trader or channel identities.
Use generated narrative summaries for questions about highlighted themes, narratives, drivers, asset sentiment, and risks. Use trader rankings for activity and performance rankings, activity summaries for counts and trends, and events, messages, positions, open positions, and stats for other exact trade facts and current positioning.
Example: positions
positionIds to hydrate positions referenced by event rows. Each row includes timeBasedPerformances for 1D, 7D, and 30D fixed windows after entry. A window value can be null when no evaluation exists for that position. When present, its status is machine-readable; ready rows include returnPercentage, while statuses such as too_young, missing_forward_price, or calculation_error explain why the fixed-window return is unavailable.
Use GET /api/v1/positions/open or list_open_positions when you need current marks, live mark-to-market returns, or current open-position skew for currently open positions.
Event flags
Event rows can includeassumed, retrospective, and autoGenerated flags. These flags explain how an event entered the position history. Normal user-facing event listings should skip assumed and auto-generated system events unless the user specifically asks about system events, missing closes, or reconstruction behavior.
See Events usage guide and Trade Classification.
Example: trader stats
summary.timeBasedPerformances for 1D, 7D, and 30D. Empty aggregates return null metrics with positionsCount: 0. Missing or inaccessible IDs are returned in data.meta.missingTraderIds.
Trader stats rows also include tags: editorial trader tags as { category, name } pairs, lowercase. The first category is thematic, the macro themes a trader’s book expresses (for example ai capex buildout or power and energy); categories are an open set and may grow over time. tags is always present and empty for untagged traders.
Example: trader rankings
event_count (default) or position_count, or by the performance metrics win_rate, avg_return, median_return, or sharpe_ratio. The window defaults to the last 7 days; pass explicit UTC startTime/endTime for other windows. Results are bounded (limit defaults to 10, maximum 50) with meta.totalCandidates reporting how many traders qualified.
Performance metrics evaluate positions at the timeBasedPerformanceWindow (defaults to 7D) and require at least minPositions evaluated positions (defaults to 3; pass minPositions=0 to include all traders). Every performance-ranked row includes timeBasedPerformance.positionsCount so thin samples can be qualified.
A position opened at time T is evaluated at T plus the evaluation window, so performance rankings require startTime to be at least the evaluation window before now. A 30D ranking over positions opened in the last week is structurally unanswerable. Such requests are rejected with a 422 (PERFORMANCE_WINDOW_NOT_ELAPSED) telling you to move startTime back or pick a shorter window.
Example: activity summaries
trader (default) or overall with groupBy=none, and bucket by hour, day (default), or week. They are not generated narrative summaries. Each group returns totals plus per-bucket messageCount and eventCount; buckets with no activity are omitted. meta.totalMessages and meta.totalEvents cover all groups, not only the returned top groups.
The window defaults to the last 7 days. Requests are rejected with 422 when the window/interval combination would produce more than 168 buckets per group. Widen the interval or narrow the window. Use eventTypes to restrict event counts and traderIds to scope groups.