United Predictions API Documentation

Overview

The Evens United Predictions API provides unified access to prediction market data across multiple providers including Kalshi, Polymarket, Smarkets, and BetRivers.

Base URL:

https://evens.app/api/v1

The API offers two types of endpoints:

Unified endpoints — Canonical markets and events with aggregated data across all providers
Provider endpoints — Raw market data from a specific provider (e.g., /api/v1/kalshi/markets)

All responses are returned as JSON. Timestamps are in ISO 8601 format. Prices are decimal values between 0 and 1.

Authentication

Authenticate requests by including your API key in the X-API-Key header.

Sign in to get your API key

API access requires a Premium subscription. Sign in or create an account to get started.

Sign in Sign up

Example

curl -H "X-API-Key: YOUR_API_KEY" \
  https://evens.app/api/v1/markets

Security: Keep your API key confidential. Do not expose it in client-side code. An active Premium subscription is required.

Rate Limits

API requests are rate limited per API key. Exceeding limits returns a 429 status.

Window	Limit
Per second	1 request (sustained)
Per minute	100 requests (burst)

Pagination

List endpoints use cursor-based pagination. Pass the cursor from the previous response to fetch the next page.

Name	Type	Description
cursor	string	Opaque cursor from previous response
limit	integer	Results per page (default: 50, max: 200)

Every paginated response includes a pagination object:

JSON

{
  "data": [...],
  "pagination": {
    "next_cursor": "MTIzNA==",
    "has_next": true
  }
}

When has_next is false, there are no more results.

Error Handling

Error responses return a JSON object with an error object:

JSON

{
  "error": {
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Status	Detail	Cause
401	Invalid or missing API key	Missing or invalid X-API-Key header
404	Resource not found	Market, event, or provider not found
429	Rate limit exceeded	Too many requests — slow down

Unified Endpoints

Canonical market and event data aggregated across all providers. Unified markets link to their provider-specific references, showing the best prices and total volume across platforms.

GET /api/v1/markets

List canonical markets with aggregated cross-provider pricing.

Parameters

Name	Type	Description
status	string	Filter by status: unopened, open, closed, finalized
market_type	string	Filter by type: moneyline, spread, total, player_prop, futures, etc.
event_id	integer	Filter by event ID
sport	string	Filter by sport (e.g., basketball, football)
competition	string	Filter by competition (e.g., nba, nfl)
provider	string	Filter to markets with coverage on this provider
search	string	Search markets by title
cursor	string	Pagination cursor
limit	integer	Results per page (default: 50, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/markets?sport=basketball&market_type=moneyline&limit=2"

Response

JSON

{
  "data": [
    {
      "id": 42,
      "title": "Lakers vs Celtics - Moneyline (LAL)",
      "market_type": "moneyline",
      "stat_type": null,
      "line": null,
      "outcome_type": "home",
      "time_qualifier": "full_game",
      "category": "sports",
      "status": "open",
      "best_yes_price": "0.55",
      "best_no_price": "0.47",
      "total_volume": "125000.00",
      "provider_coverage": ["kalshi", "polymarket"],
      "event_id": 15,
      "home_team": { "id": 1, "name": "Los Angeles Lakers" },
      "away_team": { "id": 2, "name": "Boston Celtics" },
      "person": null
    }
  ],
  "pagination": {
    "next_cursor": "NDI=",
    "has_next": true
  }
}

GET /api/v1/markets/:id

Get a canonical market with all provider references. The references array shows the same market on every platform with individual prices.

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  https://evens.app/api/v1/markets/42

Response

JSON

{
  "data": {
    "id": 42,
    "title": "Lakers vs Celtics - Moneyline (LAL)",
    "market_type": "moneyline",
    "status": "open",
    "best_yes_price": "0.55",
    "best_no_price": "0.47",
    "total_volume": "125000.00",
    "provider_coverage": ["kalshi", "polymarket"],
    "event_id": 15,
    "references": [
      {
        "id": 101,
        "provider": "kalshi",
        "external_id": "KXNBA-LAL-BOS",
        "title": "Lakers vs Celtics - LAL",
        "outcomes": {
          "yes": { "bid": "0.53", "ask": "0.55", "last_price": "0.54" },
          "no": { "bid": "0.45", "ask": "0.47" }
        },
        "volume": "75000.00",
        "url": "https://kalshi.com/markets/KXNBA-LAL-BOS"
      },
      {
        "id": 102,
        "provider": "polymarket",
        "external_id": "pm-lakers-celtics",
        "title": "Will the Lakers beat the Celtics?",
        "outcomes": {
          "yes": { "bid": "0.52", "ask": "0.56", "last_price": "0.55" },
          "no": { "bid": "0.44", "ask": "0.48" }
        },
        "volume": "50000.00",
        "url": "https://polymarket.com/event/pm-lakers-celtics"
      }
    ]
  }
}

GET /api/v1/markets/:id/prices

Get historical price snapshots for a canonical market across all providers.

Parameters

Name	Type	Description
start_time	datetime	Start of time range (ISO 8601)
end_time	datetime	End of time range (ISO 8601)
interval	string	Aggregation: raw, hourly, 4hour, daily (default: raw)
provider	string	Filter to a specific provider's prices
cursor	string	Pagination cursor
limit	integer	Results per page (default: 100, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/markets/42/prices?interval=hourly&limit=3"

Response

JSON

{
  "data": [
    {
      "timestamp": "2026-03-13T14:00:00Z",
      "aggregation_type": "hourly",
      "yes_bid": "0.53",
      "yes_ask": "0.55",
      "no_bid": "0.45",
      "no_ask": "0.47",
      "last_price": "0.54",
      "volume": "2500.00",
      "open_interest": null
    }
  ],
  "pagination": { "next_cursor": "OTk=", "has_next": true }
}

GET /api/v1/events

List canonical events with participant and market summary data.

Parameters

Name	Type	Description
sport	string	Filter by sport (e.g., basketball)
competition	string	Filter by competition (e.g., nba)
status	string	Filter by status
start_after	datetime	Events starting after this time (ISO 8601)
start_before	datetime	Events starting before this time (ISO 8601)
search	string	Search events by name
cursor	string	Pagination cursor
limit	integer	Results per page (default: 50, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/events?sport=basketball&limit=2"

Response

JSON

{
  "data": [
    {
      "id": 15,
      "title": "Boston Celtics @ Los Angeles Lakers",
      "event_identifier": "26MAR13BOSLAL",
      "event_type": "sports",
      "sport": "basketball",
      "competition": "nba",
      "status": "scheduled",
      "starts_at": "2026-03-14T02:30:00Z",
      "home_team": { "id": 1, "name": "Los Angeles Lakers" },
      "away_team": { "id": 2, "name": "Boston Celtics" },
      "market_count": 24,
      "provider_coverage": ["kalshi", "polymarket"]
    }
  ],
  "pagination": { "next_cursor": "MTU=", "has_next": true }
}

GET /api/v1/events/:id

Get a canonical event with all its markets included.

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  https://evens.app/api/v1/events/15

Response

JSON

{
  "data": {
    "id": 15,
    "title": "Boston Celtics @ Los Angeles Lakers",
    "sport": "basketball",
    "competition": "nba",
    "status": "scheduled",
    "starts_at": "2026-03-14T02:30:00Z",
    "home_team": { "id": 1, "name": "Los Angeles Lakers" },
    "away_team": { "id": 2, "name": "Boston Celtics" },
    "market_count": 24,
    "provider_coverage": ["kalshi", "polymarket"],
    "markets": [
      {
        "id": 42,
        "title": "Lakers vs Celtics - Moneyline (LAL)",
        "market_type": "moneyline",
        "status": "open",
        "best_yes_price": "0.55"
      }
    ]
  }
}

GET /api/v1/events/:event_id/markets

List all markets for a specific event.

Parameters

Name	Type	Description
market_type	string	Filter by market type
status	string	Filter by status
cursor	string	Pagination cursor
limit	integer	Results per page (default: 50, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/events/15/markets?market_type=player_prop"

Provider Endpoints

Access raw market data from a specific provider. Replace :provider with one of: kalshi, polymarket, smarkets, betrivers.

Provider endpoints return market references — the raw data from each platform including platform-specific IDs, URLs, and pricing.

GET /api/v1/:provider/markets

List market references for a specific provider.

Parameters

Name	Type	Description
status	string	Filter by status
market_type	string	Filter by market type
event_id	integer	Filter by event ID
search	string	Search by title
cursor	string	Pagination cursor
limit	integer	Results per page (default: 50, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/kalshi/markets?status=open&limit=2"

Response

JSON

{
  "data": [
    {
      "id": 101,
      "provider": "kalshi",
      "external_id": "KXNBA-LAL-BOS",
      "title": "Lakers vs Celtics - LAL",
      "market_type": "moneyline",
      "outcome_type": "home",
      "status": "open",
      "outcomes": {
        "yes": { "bid": "0.53", "ask": "0.55", "last_price": "0.54" },
        "no": { "bid": "0.45", "ask": "0.47" }
      },
      "volume": "75000.00",
      "open_interest": null,
      "liquidity": null,
      "url": "https://kalshi.com/markets/KXNBA-LAL-BOS",
      "last_synced_at": "2026-03-13T10:00:00Z",
      "market_id": 42,
      "event_id": 15
    }
  ],
  "pagination": { "next_cursor": "MTAx", "has_next": true },
  "meta": { "provider": "kalshi" }
}

GET /api/v1/:provider/markets/:id

Get a single market reference by ID from a specific provider.

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  https://evens.app/api/v1/kalshi/markets/101

GET /api/v1/:provider/markets/:id/prices

Get price history for a specific provider's market reference.

Parameters

Name	Type	Description
start_time	datetime	Start of time range (ISO 8601)
end_time	datetime	End of time range (ISO 8601)
interval	string	Aggregation: raw, hourly, 4hour, daily
cursor	string	Pagination cursor
limit	integer	Results per page (default: 100, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/kalshi/markets/101/prices?interval=daily&limit=5"

GET /api/v1/:provider/events

List event references for a specific provider.

Parameters

Name	Type	Description
status	string	Filter by status
sport	string	Filter by sport
competition	string	Filter by competition
start_after	datetime	Events starting after (ISO 8601)
start_before	datetime	Events starting before (ISO 8601)
search	string	Search by title
cursor	string	Pagination cursor
limit	integer	Results per page (default: 50, max: 200)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/polymarket/events?sport=basketball&limit=5"

GET /api/v1/:provider/events/:id

Get a single event reference by ID from a specific provider.

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  https://evens.app/api/v1/polymarket/events/55

Metadata

Discovery endpoints for sports, competitions, and supported providers.

GET /api/v1/sports

List all available sports.

Response

JSON

{
  "data": [
    { "id": 1, "name": "Basketball", "slug": "basketball" },
    { "id": 2, "name": "Football", "slug": "football" },
    { "id": 3, "name": "Baseball", "slug": "baseball" }
  ]
}

GET /api/v1/competitions

List available competitions, optionally filtered by sport.

Parameters

Name	Type	Description
sport	string	Filter by sport slug (e.g., basketball)
type	string	Filter by competition type (e.g., league, cup)

Response

JSON

{
  "data": [
    {
      "id": 1,
      "name": "NBA",
      "slug": "nba",
      "competition_type": "league",
      "sport_id": 1,
      "sport_name": "Basketball",
      "year": null,
      "season_type": null
    }
  ]
}

GET /api/v1/providers

List all supported prediction market providers with market and event counts.

Response

JSON

{
  "data": [
    { "name": "kalshi", "market_count": 4250, "event_count": 320 },
    { "name": "polymarket", "market_count": 1850, "event_count": 580 },
    { "name": "smarkets", "market_count": 920, "event_count": 150 },
    { "name": "betrivers", "market_count": 640, "event_count": 90 }
  ]
}

GET /api/v1/matching-markets

Find the same market across different providers. Supply either a canonical market ID or a provider-specific market ID to find all matching markets.

Parameters

Name	Type	Description
market_id	integer	Canonical market ID
provider	string	Provider name (use with provider_market_id)
provider_market_id	string	Provider's external market ID

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/matching-markets?provider=kalshi&provider_market_id=KXNBA-LAL-BOS"

SDKs & OpenAPI

An OpenAPI 3.1 specification is available for automated client generation:

https://evens.app/openapi/predictions.yml

Generate typed SDKs in any language using the OpenAPI Generator:

TypeScript

npx @openapitools/openapi-generator-cli generate \
  -i https://evens.app/openapi/predictions.yml \
  -g typescript-fetch \
  -o ./evens-sdk

Python

npx @openapitools/openapi-generator-cli generate \
  -i https://evens.app/openapi/predictions.yml \
  -g python \
  -o ./evens-sdk

You can also receive real-time updates via Webhooks, which push events to your server when alert conditions are met.

Quick Start

Get up and running in minutes.

1. Get your API key

Create an API key from your account page.

2. Fetch markets

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://evens.app/api/v1/markets?sport=basketball&limit=5"

3. Compare prices across providers

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://evens.app/api/v1"
headers = {"X-API-Key": API_KEY}

# Get a market with cross-provider references
market = requests.get(f"{BASE}/markets/42", headers=headers).json()

for ref in market["data"]["references"]:
    print(f"{ref['provider']}: yes={ref['outcomes']['yes']['last_price']}")

4. Get price history

Python

# Fetch hourly price snapshots for the last 24 hours
from datetime import datetime, timedelta

params = {
    "interval": "hourly",
    "start_time": (datetime.utcnow() - timedelta(hours=24)).isoformat() + "Z",
    "limit": 24
}
prices = requests.get(
    f"{BASE}/markets/42/prices",
    headers=headers,
    params=params
).json()

for p in prices["data"]:
    print(f"{p['timestamp']}: {p['last_price']}")

Overview

Authentication

Rate Limits

Pagination

Error Handling

Unified Endpoints

Parameters

Example

Response

Example

Response

Parameters

Example

Response

Parameters

Example

Response

Example

Response

Parameters

Example

Provider Endpoints

Parameters

Example

Response

Example

Parameters

Example

Parameters

Example

Example

Metadata

Response

Parameters

Response

Response

Parameters

Example

SDKs & OpenAPI

Quick Start

1. Get your API key

2. Fetch markets

3. Compare prices across providers

4. Get price history

Ready to get started?