Skip to main content
Events are the central organizing concept in the Pear API. Each Pear event represents a real-world question or outcome that has prediction markets on one or more platforms (Kalshi and Polymarket).

​
What is a Pear event?

A Pear event is a unified record that groups related prediction markets from different venues under a single identifier. For example, “Will Bitcoin reach $100K in 2025?” might exist as separate events on both Kalshi and Polymarket. Pear merges these into one event with a single pear_xxx ID. 
{
  "id": "pear_a1b2c3d4",
  "slug": "bitcoin-100k-2025",
  "title": "Bitcoin to reach $100K in 2025",
  "description": "Will Bitcoin reach $100,000 at any point during 2025?",
  "category": "Crypto",
  "source_type": "matched",
  "venue_event_ids": {
    "kalshi": "BTC-100K-2025",
    "polymarket": "0xbtc100k"
  }
}

​
Event identifiers

Each event has two identifiers:
FieldDescriptionExample
idUnique Pear identifier. Always starts with pear_.pear_a1b2c3d4
slugURL-friendly identifier. Use this in the /api/events/{slug} endpoint.bitcoin-100k-2025

​
Source types

The source_type field tells you how the event was sourced across platforms:
Source typeDescriptionCount
matchedThe event exists on both Kalshi and Polymarket. The venue_event_ids object will have both kalshi and polymarket keys.~4,400
kalshi_onlyThe event only exists on Kalshi.~3,500
polymarket_onlyThe event only exists on Polymarket.~3,600
Use this field to find events that are available for cross-platform comparison: 
# Only events on both platforms
curl "http://localhost:8000/api/events?source_type=matched&limit=10" \
  -H "Authorization: Bearer mk_live_..."

​
Venue event IDs

The venue_event_ids field maps venue names to their native event identifiers. This lets you cross-reference Pear events with the original platforms. 
// Matched event - both platforms
"venue_event_ids": {
  "kalshi": "BTC-100K-2025",
  "polymarket": "0xbtc100k"
}

// Kalshi-only event
"venue_event_ids": {
  "kalshi": "FED-RATE-MAR25"
}

// Polymarket-only event
"venue_event_ids": {
  "polymarket": "0xpresidential2028"
}

​
Categories

Events are organized into categories that reflect the topic area. The available categories and their event counts can be fetched via the /api/events/categories endpoint. Common categories include:
  • Sports — Super Bowl, NBA, MLB, soccer, and other sporting events
  • Elections — Presidential, congressional, gubernatorial races
  • Politics — Policy decisions, appointments, geopolitical events
  • Economics — Fed rate decisions, inflation, GDP, employment
  • Crypto — Bitcoin price targets, ETF approvals, protocol milestones
  • Entertainment — Awards shows, box office, streaming metrics
  • Science — Space exploration, climate milestones, research breakthroughs
  • Technology — Product launches, company milestones, AI developments
  • Weather — Temperature records, hurricane forecasts, seasonal patterns
Filter events by category: 
curl "http://localhost:8000/api/events?category=Economics&limit=10" \
  -H "Authorization: Bearer mk_live_..."

​
Events and markets

Each event can have one or more venue markets — the actual tradeable contracts listed on Kalshi or Polymarket. For example, a “Super Bowl LIX” event might have separate markets for the winner, the MVP, the total score, and various prop bets. Fetch an event with all its markets: 
curl "http://localhost:8000/api/events/super-bowl-lix-2025" \
  -H "Authorization: Bearer mk_live_..."
Or fetch just the markets, optionally filtered by venue: 
# All markets for this event
curl "http://localhost:8000/api/events/super-bowl-lix-2025/markets" \
  -H "Authorization: Bearer mk_live_..."

# Only Polymarket markets
curl "http://localhost:8000/api/events/super-bowl-lix-2025/markets?venue=polymarket" \
  -H "Authorization: Bearer mk_live_..."
See the Markets guide for details on market pricing, volume, and other fields.

​
Listing and filtering events

The /api/events endpoint supports filtering and cursor-based pagination: 
import requests

headers = {"Authorization": "Bearer mk_live_..."}

# Get first page of crypto events
response = requests.get(
    "http://localhost:8000/api/events",
    params={"category": "Crypto", "source_type": "matched", "limit": 50},
    headers=headers
)
page = response.json()

print(f"Total: {page['total_count']} events")
for event in page["data"]:
    print(f"  {event['title']}")

# Get next page
if page["has_more"]:
    next_response = requests.get(
        "http://localhost:8000/api/events",
        params={"category": "Crypto", "source_type": "matched", "limit": 50, "cursor": page["next_cursor"]},
        headers=headers
    )
See the Pagination guide for more on navigating large result sets.