API documentation

The Sleven Intelligence API: live prediction-market data for AI and technology events, model fair values, divergence alerts, structured event intelligence, and a public calibration record — over REST and WebSocket.

base url https://api.sleven.ai

§ Authentication

Every request under /v1 requires an API key. Send it as a Bearer token (preferred) or an x-api-key header. Keys look like sk_live_…, are shown once at issuance, and are stored only as hashes — if you lose one, revoke it and issue a new one.

curl https://api.sleven.ai/v1/contracts \
  -H "Authorization: Bearer sk_live_your_key_here"

# equivalent:
curl https://api.sleven.ai/v1/contracts -H "x-api-key: sk_live_your_key_here"

§ Tiers & rate limits

Tier	Data	Streaming	Rate limit
free	24-hour delayed	—	60 req/min
prosumer	live	—	300 req/min
b2b	live	WebSocket push	1,200 req/min

Limits use a fixed one-minute window. Every response carries the current state; exceeding the limit returns 429 with a retry-after header.

x-ratelimit-limit: 300
x-ratelimit-remaining: 287
x-ratelimit-reset: 41        # seconds until the window resets

§ Data freshness (asOf)

Every data response includes an asOf timestamp — the moment the world is described at. For live tiers this is now; for the free tier it is 24 hours ago, and all quotes, fair values, alerts, and events are consistently served as of that time. Settled calibration data (/v1/calibration) is historical and never delayed.

§ Market data

GET/v1/contracts

All open contracts with their latest quote and fair value. Contracts are Kalshi and Polymarket binary markets in the AI and technology domains; prices are probabilities in [0, 1].

curl https://api.sleven.ai/v1/contracts -H "Authorization: Bearer $KEY"

response

{
  "asOf": "2026-08-05T14:00:00.000Z",
  "contracts": [
    {
      "id": "5cbee0f4-…",
      "exchange": "kalshi",
      "ticker": "KXTOPMODEL-26AUG10-CLAUM",
      "title": "Top model on Arena on Aug 10?",
      "family": "top_model_monthly",
      "domain": "ai",
      "status": "open",
      "close_at": "2026-08-10T14:00:00.000Z",
      "bid": 0.86, "ask": 0.89, "mid": 0.875, "last": 0.87,
      "quoted_at": "2026-08-05T13:59:41.000Z",
      "p_fair": 0.703,
      "fair_valued_at": "2026-08-05T13:05:12.000Z"
    }
  ]
}

GET/v1/fair-values

Latest model fair value per open contract, with the component breakdown (prior, market, LLM judgment weights) and the live market mid for comparison.

curl https://api.sleven.ai/v1/fair-values -H "Authorization: Bearer $KEY"

response

{
  "asOf": "2026-08-05T14:00:00.000Z",
  "fairValues": [
    {
      "id": "5cbee0f4-…",
      "ticker": "KXTOPMODEL-26AUG10-CLAUM",
      "p_fair": 0.703,
      "p_market": 0.875,
      "computed_at": "2026-08-05T13:05:12.000Z",
      "components": {
        "prior": 0.83, "norm_mid": 0.87, "llm_p": 0.55,
        "base_weight": 0.25, "llm_weight": 0.3,
        "model_version": "fair-value-v2-llm-judgment"
      }
    }
  ]
}

GET/v1/alerts

Divergence alerts: moments where the model's fair value and the market price disagreed by more than the liquidity-aware threshold. edge_bps is (fair − market) in basis points; positive means the model considered YES underpriced.

curl https://api.sleven.ai/v1/alerts -H "Authorization: Bearer $KEY"

response

{
  "asOf": "2026-08-05T14:00:00.000Z",
  "alerts": [
    {
      "id": "7c0e17a2-…",
      "ticker": "KXTOPMODEL-26AUG10-CLAUM",
      "p_fair": 0.703, "p_market": 0.875,
      "edge_bps": -1719,
      "emitted_at": "2026-08-05T05:43:12.000Z"
    }
  ]
}

GET/v1/contracts/{id}/timeline

Everything known about one contract: 15-minute price buckets, fair-value history, alerts, linked intelligence events, lifecycle transitions, and resolution-text edits.

days	History window, 1–90 (default 14)

curl "https://api.sleven.ai/v1/contracts/5cbee0f4-…/timeline?days=30" \
  -H "Authorization: Bearer $KEY"

response

{
  "asOf": "…",
  "contract": { "id": "…", "ticker": "…", "resolution_text": "…", … },
  "ticks":          [ { "bucket": "…", "mid": 0.87, "bid": 0.86, "ask": 0.89 } ],
  "fairValues":     [ { "time": "…", "p_fair": 0.703, "components": { … } } ],
  "alerts":         [ … ],
  "events":         [ … ],
  "lifecycle":      [ { "from_status": "open", "to_status": "resolved", … } ],
  "resolutionDiffs":[ { "old_text": "…", "new_text": "…", "detected_at": "…" } ]
}

GET/v1/contracts/{id}/media

Media & sources for one contract: the inputs that actually feed its fair value (derived from the published components — the generic tier uses market price only), the entity-registry row (canonical entities, aliases, resolution class), and linked media coverage. usedInCalculation distinguishes calculation inputs from context.

curl "https://api.sleven.ai/v1/contracts/5cbee0f4-…/media" \
  -H "Authorization: Bearer $KEY"

response

{
  "asOf": "…",
  "contract": { "id": "…", "ticker": "…", "family": "…", … },
  "fairValue": { "pFair": 0.703, "computedAt": "…", "modelVersion": "fair-value-v2-llm-judgment" },
  "registry": {
    "entities": [ { "kind": "company", "name": "Epic Games", "aliases": [ "fortnite maker" ] } ],
    "resolution_class": "company-event-by-date",
    "confidence": 0.9
  },
  "inputs": [
    { "kind": "settled-history", "detail": "persistence prior …", "weight": 0.25 },
    { "kind": "market", "detail": "event-normalized market mid", "weight": 0.45 },
    { "kind": "llm-judgment", "detail": "frontier judgment …", "weight": 0.3, "rawEventId": "…" }
  ],
  "mediaSources": [
    {
      "source": "lmarena", "sourceClass": "benchmark",
      "url": "https://arena.ai/leaderboard/…",
      "eventType": "leaderboard-change", "confidence": 0.92,
      "linkMethod": "family-benchmark", "linkScore": null,
      "seenAt": "…", "usedInCalculation": true
    }
  ]
}

§ Intelligence

GET/v1/events

Recent enriched events extracted from monitored sources (leaderboards, arXiv, engineering blogs, news, X): typed, entity-tagged, confidence-scored, and linked to the contracts they touch.

curl https://api.sleven.ai/v1/events -H "Authorization: Bearer $KEY"

response

{
  "asOf": "…",
  "events": [
    {
      "id": "91d2c3aa-…",
      "event_type": "benchmark_update",
      "entities": [ { "kind": "model", "name": "claude-opus-5-max" } ],
      "confidence": 0.93,
      "source": "lmarena", "source_class": "benchmark",
      "url": "https://arena.ai/leaderboard/…",
      "linked_contracts": 6,
      "created_at": "…"
    }
  ]
}

GET/v1/entities/{name}

Entity view: the canonical entity (models, labs, benchmarks) if known, recent events mentioning the name (case-insensitive, matches aliases), and the contracts those events link to.

curl https://api.sleven.ai/v1/entities/claude-opus-5-max \
  -H "Authorization: Bearer $KEY"

response

{
  "asOf": "…",
  "entity": { "kind": "model", "name": "claude-opus-5-max", "aliases": [ … ] },
  "events":    [ … ],
  "contracts": [ … ]
}

§ Calibration record

GET/v1/calibration

The public track record, machine-readable: every published fair value and alert graded against reality once its contract settles. brier_ours vs brier_market is the headline comparison (lower is better). Settled-only, so no tier delay applies.

curl https://api.sleven.ai/v1/calibration -H "Authorization: Bearer $KEY"

response

{
  "aggregate": [
    { "kind": "fair_value", "settled": 130,
      "brier_ours": 0.142, "brier_market": 0.158 }
  ],
  "settled": [
    { "kind": "fair_value", "ticker": "…", "p": 0.703, "p_market": 0.875,
      "resolved_outcome": true, "brier": 0.088, "resolved_at": "…" }
  ],
  "pending": [ { "kind": "fair_value", "pending": 170 } ]
}

§ Bulk export

GET/v1/export/ticks

Raw quote history for one contract as CSV (default) or JSON. Up to 100,000 rows per request.

contract_id	Contract UUID (required)
days	History window, 1–90 (default 30)
format	csv (default) or json

curl -OJ "https://api.sleven.ai/v1/export/ticks?contract_id=5cbee0f4-…&days=90" \
  -H "Authorization: Bearer $KEY"

response

time,bid,ask,mid,last
2026-08-01T00:01:12.000Z,0.84,0.87,0.855,0.86
2026-08-01T00:04:41.000Z,0.85,0.87,0.86,0.86
…

GET/v1/export/contracts

The full catalog (all statuses) with latest mid and fair value, as CSV or JSON.

format

csv (default) or json

curl -OJ https://api.sleven.ai/v1/export/contracts -H "Authorization: Bearer $KEY"

response

exchange,ticker,title,family,domain,status,close_at,mid,p_fair
kalshi,KXTOPMODEL-26AUG10-CLAUM,"Top model…",top_model_monthly,ai,open,…,0.875,0.703
…

§ Usage

GET/v1/usage

Self-service metering for the presented key: requests per day per route over the last 14 days.

curl https://api.sleven.ai/v1/usage -H "Authorization: Bearer $KEY"

response

{
  "tier": "b2b",
  "usage": [
    { "day": "2026-08-05", "route": "/v1/contracts", "requests": 1440 },
    { "day": "2026-08-05", "route": "/v1/ws", "requests": 12 }
  ]
}

§ WebSocket streaming

The push plane at wss://…/v1/ws delivers ticks, fair values, and alerts in real time. It requires the b2b tier (or a key with the stream scope). Every event carries a seq — sequence numbers are strictly increasing per stream, and a client that reconnects with the last seq it saw receives an exact replay of everything it missed before live delivery resumes: no gaps, no duplicates.

Rooms

alerts	every divergence alert
fair-values	every fair-value publish (all contracts)
fair-values:{contractId}	fair values for one contract
ticks	every quote change (firehose)
ticks:{contractId}	quote changes for one contract

Protocol

# connect, then authenticate within 10 seconds
→ { "type": "auth", "key": "sk_live_…" }
← { "type": "auth_ok", "tier": "b2b", "name": "your-app" }

# subscribe; pass "since" per room to replay everything you missed
→ { "type": "subscribe",
    "rooms": ["alerts", "ticks:5cbee0f4-…"],
    "since": { "alerts": "1785921619554-0" } }
← { "type": "subscribed", "room": "alerts", "replayFrom": "1785921619554-0" }
← { "type": "event", "room": "alerts", "seq": "1785921620001-0",
    "data": { "ticker": "…", "pFair": 0.703, "pMarket": 0.875,
              "edgeBps": -1719, "emittedAt": "…" }, "replayed": true }
← { "type": "replay_done", "room": "alerts", "seq": "1785921665002-0" }
# …live events follow, same shape, no "replayed" flag

# keepalive (the server also sends protocol-level pings every 30s)
→ { "type": "ping" }   ← { "type": "pong", "t": 1785921700000 }

# housekeeping
→ { "type": "unsubscribe", "rooms": ["ticks:5cbee0f4-…"] }

Persist the last seq per room; on reconnect, authenticate and resubscribe with it as since. Close codes: 4401 auth failed or timed out, 4403 no streaming entitlement. Server-to-server clients may skip the auth message by sending the Authorization header on the upgrade request.

§ Errors

401	missing, invalid, or revoked API key
429	rate limit exceeded — honor retry-after
400	malformed parameter (e.g. non-UUID contract_id)
404	resource not found

{ "error": "invalid or missing API key (Authorization: Bearer sk_...)" }