> ## Documentation Index
> Fetch the complete documentation index at: https://partners.centaur.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent and Client Contract Limits

> Important limits and unsupported inferences for REST, MCP, and agent clients.

Centaur exposes read-only data. Some useful client workflows require multiple reads or cannot be answered exactly from the public contract.

## Hard limits

| Limit                        | Current behavior                                                                                                                               |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| List page size               | `limit` accepts up to `200` on general list reads. The partner feed counts source-message groups instead of rows: default `20`, maximum `100`. |
| Stats batch size             | Trader and asset stats accept up to `200` IDs.                                                                                                 |
| Position performance windows | Public position performance is `1D`, `7D`, and `30D`.                                                                                          |
| Messages filters             | Messages support `ids`, `sourcePlatforms`, `startTime`, `endTime`, `limit`, and `cursor`; not trader, asset, direction, or event-type filters. |
| Stats inputs                 | Trader stats require explicit `traderIds`; asset stats require explicit `assetIds`.                                                            |
| Aggregate result size        | Trader rankings and activity summaries return at most `50` rows or groups with no pagination.                                                  |
| Activity summary buckets     | Window/interval combinations above `168` buckets per group are rejected with `422`.                                                            |
| Performance ranking windows  | Performance-metric rankings require `startTime` at least the evaluation window before now; more recent windows are rejected with `422`.        |

## Unsupported as single reads

These requests can be useful, but they are not single endpoint/tool contracts:

* top trader-asset pairs
* exact "best and worst trades" without defining sample and metric
* "who should I fade" without a concrete metric and sample
* predictive questions like "where does this asset go next"

Agents may answer some of these as heuristic multi-step workflows, but they should label the method and avoid presenting it as an exact public endpoint.

Trader ranking questions are supported as a single read: use `GET /api/v1/traders/rankings` or `rank_traders` with an explicit metric and time window instead of paging raw events. Message/event count and trend questions are supported through `GET /api/v1/activity-summaries` or `summarize_message_activity`.

## Current positioning

Use open-position reads for current positioning and open-position skew.

Do not use generated narrative summaries as evidence for:

* exact trade counts
* public activity rankings
* current open-position skew
* full-universe consensus

## Performance

Use stats and position history for performance. Public performance evaluation uses Time-Based Performance windows, not a public close-return mode.

If a position performance value is unavailable, the response can return a status such as `too_young`, `missing_forward_price`, `missing_entry_price`, `zero_entry_price`, or `calculation_error`. Treat that as unavailable data, not zero return.

## Pagination

If a paginated response has `meta.hasMore=true`, the current page is partial. Agents should fetch more pages or explicitly qualify the answer as partial.

Pagination is for itemized reads only. For ranking, count, and trend questions, use trader rankings or activity summaries instead of walking pages: they return bounded, already-aggregated results.

Pagination reflects the current eligible result set. It is not a frozen snapshot.

## Rate limits

Each API key has a request allowance. The default is `1000` requests, replenished in full one hour after the previous replenishment. Exhausting the allowance returns `429` with code `RATE_LIMITED` and, when available, a `Retry-After` header. Production limits vary by account or environment.

Handle `429` as a normal retry/backoff condition.