Skip to content

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.

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
Terminal window
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.

Terminal window
curl -sS -H "Authorization: Bearer $COTES_API_KEY" \
"https://api.cotes.ai/v1/contests/active?series=KXBTC15M"
Terminal window
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.

Terminal window
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:

Terminal window
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.

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.

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.