Contests & signals
A contest is one prediction-market interval (ticker). Responses include every Cotes AI reading for that contest — confidence, entry price, edge, outcome, and whether SpectralEdge showed it as a signal (fired). Use fired for SpectralEdge’s own calls, or apply your own thresholds in your client.
Series
Section titled “Series”Contests come in series, one per asset. Every contest endpoint and the stream take the series prefix.
| Series | Asset |
|---|---|
KXBTC15M |
Bitcoin |
KXETH15M |
Ethereum |
KXSOL15M |
Solana |
KXXRP15M |
XRP |
curl -sS -H "Authorization: Bearer $COTES_API_KEY" \ "https://api.cotes.ai/v1/series"{ "series": [ { "series": "KXBTC15M", "asset": "BTC", "name": "Bitcoin 15-minute", "active_ticker": "KXBTC15M-26NOV121430-30", "model_version": "34fa82b3", "last_signal_at": "2026-11-12T14:21:05Z" } ]}active_ticker is the round trading now, and null in the changeover between rounds. model_version and last_signal_at describe the newest signal stored for the series; both are null for a series that has no signals yet. Catalog membership does not establish that a signal producer is running. An empty signals list means no readings were stored for that contest. A stale last_signal_at remains visible after a producer stops. Older readings may have a null model_version even when last_signal_at is set.
The examples below use KXBTC15M. Swap in another series and the calls and shapes are the same.
The catalog lists crypto markets, not every recorded market. Existing contest endpoints also accept recorded series such as KXGOLD15M; GOLD is outside the supported crypto signal catalog. The parameterized MCP resource follows the same REST behavior.
GET /v1/health reports service readiness. Its legacy model_version is the BTC bundle shipped with the API build, explicitly labeled by model_series: KXBTC15M. Use /v1/series and individual signals for production model provenance.
Fetch active contest
Section titled “Fetch active contest”curl -sS -H "Authorization: Bearer $COTES_API_KEY" \ "https://api.cotes.ai/v1/contests/active?series=KXBTC15M"Fetch by ticker
Section titled “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
Section titled “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.
A settled round lists every reading raised during it, one every few seconds, so 20 rounds is several thousand readings. Pass fired_only=true to list only the readings with fired: true in each round:
curl -sS -H "Authorization: Bearer $COTES_API_KEY" \ "https://api.cotes.ai/v1/contests?series=KXETH15M&limit=20&fired_only=true"Leave it off when you apply your own thresholds, since those need the readings that did not fire.
Signal fields
Section titled “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 |
fired |
boolean | Whether SpectralEdge showed this reading as a signal |
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.
fired is true when the reading cleared SpectralEdge’s confidence, edge and distance-from-strike thresholds for its series that were in force when it was raised. A later change to those thresholds does not change fired on readings already raised. Readings that did not fire are still listed, so a hit rate of SpectralEdge’s calls counts the first reading with fired: true in each settled contest.
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.
Every contest names its series and its asset (BTC, ETH, SOL or XRP). strike_price_dollars and settled_price_dollars are in the asset’s own dollar price: tens of thousands for Bitcoin, a few dollars with fractions of a cent for XRP. Decode them as floats, and don’t compare distances from the strike across assets in dollars.
Between rounds
Section titled “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'. The next round opens shortly; retry in a few seconds."}That is the changeover response, not a bad key — retry shortly, or hold a stream open and wait for contest.opened. A series the API has nothing recorded for returns the same 404 and never resolves; its detail says the series is not in the catalog. If a 404 persists past a few seconds, check the prefix against GET /v1/series. /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.