Prediction Market API

The Prediction Market API is a standalone order book and matching engine for binary prediction markets. It provides operators with the tools to create markets, accept orders from players, match trades, track positions, and settle resolved markets.

Architecture Overview

The platform operates on a multi-tenant model where each Operator manages their own markets and players independently. The prediction engine handles:

• Market Management — Create, open, suspend, resume, close, resolve, and settle markets
• Order Matching — Continuous limit order book with price-time priority matching
• Position Tracking — Aggregate position data per operator per outcome
• Settlement — Record payouts for winning positions after market resolution
• Real-time Data — WebSocket streaming, webhooks, and event replay for reliable delivery

Integration Model

┌──────────────┐         ┌─────────────────────┐
│   Operator   │────────▶│  Prediction Market   │
│   Backend    │  REST   │       Engine         │
│              │  gRPC   │                      │
│  - Users     │  WS     │  - Markets           │
│  - Wallets   │◀────────│  - Order Book        │
│  - Sessions  │ Webhooks│  - Matching          │
│              │         │  - Positions          │
└──────────────┘         │  - Settlements        │
                         └─────────────────────┘

Operators are responsible for:

• Managing player accounts and sessions
• Managing player wallet balances
• Validating that a player can afford an order before submitting it
• Crediting player wallets based on settlement payout data

The Prediction Engine is responsible for:

• Market lifecycle management
• Order validation (market status, price/share bounds, sell-side position checks)
• Order matching and trade execution
• Position aggregation
• Settlement record creation with payout amounts

API Interfaces

Interface	Protocol	Default Port	Use Case
REST API	HTTP/JSON	8084	Primary integration — market management, trading, queries
gRPC	Protocol Buffers	50055	High-performance integration — low latency order placement
WebSocket	WS/JSON	8084 (/ws)	Real-time streaming — prices, trades, order book updates
Webhooks	HTTP POST	—	Backend-to-backend event delivery with HMAC signing
Event Replay	HTTP/JSON	8084	Fetch missed events (24-hour retention)

Quick Example

# 1. Create a market
curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Will it rain tomorrow?",
    "description": "Resolves YES if rainfall > 0mm recorded by 11:59 PM",
    "outcomes": [
      { "name": "Yes" },
      { "name": "No" }
    ]
  }'

# 2. Open the market for trading
curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets/{marketId}/open \
  -H "X-Api-Key: your-api-key"

# 3. Place an order on behalf of a player
curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/orders \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "{marketId}",
    "outcomeId": "{outcomeId}",
    "playerId": "player-123",
    "side": "BUY",
    "type": "LIMIT",
    "shares": 10,
    "price": 0.65
  }'