Skip to main content
Use this page to choose the right Centaur read surface without scanning the full generated reference first.

​
Capability map

​
Observable behavior across reads

  • Operations are scope-gated. A key may work on some endpoint families and return 403 on 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 priceAsOf field.

​
Example: trader identity lookup

The directory returns id, name, slug, avatarUrl, and a singular nullable source. Search matches trader names/slugs and assigned source names, handles, or profile URLs. A trader can appear without messages, positions, or an assigned source. Either message or signal visibility must permit the caller. Directory access does not grant content access.

​
Example: select traders by position count

Activity rows contain traderId and positionCount. This read requires stats.read and signal visibility. Counts exclude deleted positions and assets without an active market. Optional bounds apply inclusively to position open time; omitted bounds are unbounded. minPositionCount defaults to 3; 0 includes zero-position traders, although an asset filter still requires a matching eligible position. Results are alphabetical and paginated. Resolve IDs through the directory when names are needed. Use trader stats for performance metrics. GET /v1/traders and list_traders retain their existing contract. See Trader directory migration.

​
Example: asset discovery

Asset discovery accepts an optional assetClass filter on both REST versions and MCP list_assets. Supported values are crypto, stocks, indices, commodities, and fx. Multiple values match any selected class and intersect with search, assetIds, and traderIds.
For MCP, pass an array such as {"assetClass":["stocks","indices"],"limit":10}. REST and MCP also accept comma-separated strings. Omit the filter or pass an empty value for all classes, including other. all, equities, and other are not filter values. Invalid values cause a validation error. Keep the same filters when requesting the next cursor page. Each discovery result includes two class fields:
  • assetClass is the raw class: crypto, equities, commodities, fx, or other.
  • resolvedAssetClass splits equities into stocks and indices, matching the web app’s market filters.
An equity with an Indices category resolves to indices; other equities resolve to stocks. Unknown or missing classes return other in both fields. Assets still need an active market to appear in discovery results.

​
Example: messages

GET /v2/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. Each message returns traderId. Pass traderIds to select messages from the assigned source of those traders, independently of signal visibility. Resolve names and handles through the trader directory first; message access still requires messages.read and message visibility. 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

The partner feed groups curated events by Source Message ID and embeds the source, trader, and asset display fields needed for rendering. Use 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

Generated channel narrative summaries are compact by default. They return 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

Generated aggregate narrative summaries synthesize the Aggregate Window across eligible sources. They return a headline, overview, dominant narratives, contrarian theses, market drivers, asset sentiment, risks, source coverage counts, and pagination metadata. 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 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

Positions include open and closed rows selected by position open time. Pass 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 /v2/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 include assumed, 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

Trader stats include summary.timeBasedPerformances for 1D, 7D, and 30D. Each window reports sampled and scored position counts plus their ratio under coverage. 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

Trader rankings answer “most active” and “best performing” questions server-side, without requiring trader IDs and without paging raw events. Rank by the activity metrics event_count (default) or position_count, or by the performance metrics win_rate, avg_return, median_return, or sharpe_ratio. An omitted sample defaults to UTC year-to-date. Omitted bounds are defaulted independently, so an explicit bound is never changed. 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 30D) and require at least minPositions scored positions (defaults to 3; pass minPositions=0 to include all traders). Every performance-ranked row includes timeBasedPerformance.coverage with sampled and scored position counts plus their ratio. No additional coverage percentage threshold is applied. A position opened at time T is evaluated at T plus the evaluation window. If no position in the resolved sample can have reached that window, the API returns 422 (PERFORMANCE_WINDOW_NOT_ELAPSED). The error includes the requested and resolved values plus valid retry alternatives. The API does not change the requested windows or retry automatically.

​
Example: activity summaries

Activity summaries return deterministic message and event counts, valid evidence for counts, volumes, and trends. They group by 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.

​
Next steps

Last modified on September 15, 2026