Contests & signals

A contest is one prediction-market interval (ticker). Responses include the Cotes AI signals for that contest — confidence, entry price, edge, and outcome. Apply your own thresholds in your client.

Fetch active contest

curl -sS -H "Authorization: Bearer $COTES_API_KEY" \
  "https://api.cotes.ai/v1/contests/active?series=KXBTC15M"

Fetch by ticker

curl -sS -H "Authorization: Bearer $COTES_API_KEY" \
  "https://api.cotes.ai/v1/contests/KXBTC15M-26AUG061600-00"

A ticker is the venue’s own contest identifier, including its trailing suffix — treat it as opaque and take it from the ticker field of /v1/contests/active or a stream event rather than constructing one. Truncated or invented tickers return 404.

Fetch settled history

curl -sS -H "Authorization: Bearer $COTES_API_KEY" \
  "https://api.cotes.ai/v1/contests?series=KXBTC15M&limit=20"

Settled rounds for a series, newest first, each with its signals already graded — this is how you measure our signals rather than watch them. Live rounds are excluded: their signals are still pending.

{ "contests": [ { "ticker": "KXBTC15M-26AUG061600-00", "state": "settled", "…": "…" } ] }

limit defaults to 20 and caps at 100. since and before are ISO-8601 instants windowing on window.expires_at, which for a 15-minute round is its settlement time. before is inclusive, so paginate by passing the oldest expires_at you received and discarding the repeated first row. An unknown series returns 200 with an empty array, not 404.

Signal fields

Field	Type	Meaning
`ticker`	string	Contest ticker (same as parent)
`raised_at`	string	ISO-8601 UTC (natural key with ticker)
`side`	string	`up` \| `down`
`confidence`	number	Model probability for `side`, `0`–`100`
`entry_price_cents`	number	Venue quote for `side` on the 0–100¢ scale (`$0.54` → `54.0`)
`edge_cents`	number	`confidence − entry_price_cents`
`outcome`	string	`pending` \| `win` \| `loss` \| `void`
`model_version`	string \| null	Tag of the model that produced this reading

confidence, entry_price_cents and edge_cents are JSON numbers carrying up to two decimals (81.37, 54.0) — decode them as floats or decimals, not integers.

model_version changes only when a new model is deployed, so it groups readings by the model behind them — use it to keep two models’ records apart when you measure our signals over time. It is null on readings stored before the tag was recorded.

Contests also include settlement fields such as settled_side and settled_price_dollars when available. See the API reference for the full schema.

Between rounds

A series runs one contest at a time, and its rounds run back to back — a KXBTC15M round is 15 minutes, and the next opens as the previous expires. In the moment between the two, /v1/contests/active returns 404:

{
  "type": "https://api.cotes.ai/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No live contest for series 'KXBTC15M'."
}

That is the changeover response, not a bad key or an unknown series — retry shortly, or hold a stream open and wait for contest.opened. /v1/contests/{ticker} keeps returning a round after it settles, so a ticker you already have stays fetchable.

Both endpoints are throttled — see Rate limits.