Skip to main content

Getting Started

This guide walks you through the steps to integrate with the Prediction Market API as an operator.

Prerequisites​

Before you begin, you need:

  1. Operator Account — A registered operator account with API credentials
  2. API Key — Your unique API key for authenticating requests

Contact a platform administrator to have your operator account created. You will receive an API Key for authenticating all API requests.

Base URL​

REST API:  http://{host}:8084
gRPC:      {host}:50055
WebSocket: ws://{host}:8084/ws

Authentication​

All API calls require the X-Api-Key header:

curl -H "X-Api-Key: your-api-key" https://polymarket.sandbox.playbatman.com/api/v1/markets

See the Authentication page for details.

Integration Flow​

Step 1: Create a Category (Optional)​

Categories help organize your markets.

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/categories \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sports",
    "slug": "sports",
    "description": "Sports prediction markets"
  }'

Step 2: 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": "Champions League Final Winner",
    "description": "Which team will win the 2026 Champions League final?",
    "categoryId": "{categoryId}",
    "currency": "KES",
    "tradingStartsAt": "2026-03-01T00:00:00Z",
    "tradingEndsAt": "2026-06-01T00:00:00Z",
    "outcomes": [
      { "name": "Team A" },
      { "name": "Team B" }
    ]
  }'

The market is created in DRAFT status.

Step 3: Open the Market​

When ready, 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"

Step 4: Place Orders​

Submit orders on behalf of your players. You must validate on your side that the player has sufficient balance before placing a BUY order.

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-456",
    "side": "BUY",
    "type": "LIMIT",
    "shares": 100,
    "price": 0.55,
    "transactionId": "txn-abc-123"
  }'

The response includes the order details and any immediate trades if the order was matched.

Step 5: Monitor Positions​

Track your operator's aggregate positions:

curl https://polymarket.sandbox.playbatman.com/api/v1/positions \
  -H "X-Api-Key: your-api-key"

Step 6: Resolve and Settle​

Once the event outcome is known:

# Resolve the market
curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets/{marketId}/resolve \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "winningOutcomeId": "{outcomeId}",
    "resolutionSource": "Official match result",
    "resolutionNotes": "Team A won 3-1"
  }'

# Trigger settlement
curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets/{marketId}/settle \
  -H "X-Api-Key: your-api-key"

# Query settlement payouts
curl https://polymarket.sandbox.playbatman.com/api/v1/settlements?marketId={marketId} \
  -H "X-Api-Key: your-api-key"

Settlement records tell you how much each position pays out. Use this data to credit your players' wallets.

Market Lifecycle​

DRAFT → UPCOMING → OPEN → SUSPENDED → OPEN (resumed)
                     ↓                    ↓
                   CLOSED → RESOLVED → SETTLED
                     ↓
                 CANCELLED
StatusDescription
DRAFTMarket created, not yet visible or tradeable
UPCOMINGMarket visible, trading not yet started
OPENMarket open for trading
SUSPENDEDTrading temporarily paused
CLOSEDTrading ended, awaiting resolution
RESOLVEDWinning outcome declared, awaiting settlement
SETTLEDAll positions settled, payouts recorded
CANCELLEDMarket cancelled, all orders cancelled

Response Format​

All REST API responses follow a consistent envelope:

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": {
    "code": "MARKET_NOT_FOUND",
    "message": "Market with id xyz not found"
  }
}

Next Steps​