Predictions & events

Two related surfaces: events (the public market catalog — no auth) and predictions (subnet forecasts for those events — API key required). All read endpoints are free.

Events (public)

List events

curl "https://api.almnc.ai/v1/events?limit=20&q=bitcoin&sortBy=volume"

Useful query parameters: limit, cursor (keyset pagination), q (text search), source, tagId, includeEnded, hasResolution, liquidity, volume, min_price, max_price, sortBy. The response is a PaginatedEventsDto: an items array plus a nextCursor to pass back as cursor. See the API reference for the full parameter list and schema.

Single & random events

curl https://api.almnc.ai/v1/events/EVENT_ID
curl "https://api.almnc.ai/v1/events/random?seed=42"

random supports the same filters as the list plus a seed for reproducible sampling.

Predictions (API key)

Latest prediction for an event

Requires scope predictions:read:

curl https://api.almnc.ai/v1/predictions/EVENT_ID \
  -H "Authorization: Bearer $ALMANAC_API_KEY"

Request a fresh forecast

Requires scope predictions:write:

curl -X POST https://api.almnc.ai/v1/predictions/query \
  -H "Authorization: Bearer $ALMANAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventId": "EVENT_ID" }'

An optional options object passes forecast parameters through to the inference pipeline.

Prediction history

Requires scope history:read. Paginates with limit (1–500) and an opaque cursor:

curl "https://api.almnc.ai/v1/predictions/EVENT_ID/history?limit=100" \
  -H "Authorization: Bearer $ALMANAC_API_KEY"

Take nextCursor from each page and pass it as cursor until it comes back empty.

Pagination pattern

Both surfaces use keyset cursors — stable under concurrent writes, no page-number drift:

GET …?limit=100          → { items: […], nextCursor: "abc" }
GET …?limit=100&cursor=abc → { items: […], nextCursor: "def" }
…until nextCursor is null.

Treat cursors as opaque: don't parse or construct them.