XO Markets API Documentation

Welcome to the XO Markets API documentation. Build prediction market trading applications with our comprehensive, institution-grade API.

About XO Markets

XO Markets is the leading prediction market infrastructure provider, offering a robust API that enables developers to embed prediction market trading functionality into their applications.

Key Features

• Real-time market data for thousands of global event markets
• Instant order execution with sub-50ms latency
• Institutional-grade compliance with SOC 2, ISO 27001, and GDPR
• Global coverage across politics, finance, sports, entertainment, and more

Use Cases

Quick Start

Step 1: Create an Account

Sign up for an XO Markets account at app.xotrade.co. You'll receive API credentials immediately upon registration.

Step 2: Get Your API Keys

After registration, navigate to the API Keys section in your dashboard.

Step 3: Install the SDK

pip install xo-trade

npm install @xo-trade/sdk

Step 4: Make Your First Request

from xo_trade import XO

# Initialize client
client = XO.Client(
    api_key='pk_live_your_key',
    api_secret='sk_live_your_secret'
)

# Get account info
account = client.get_account()
print(f"Balance: ${account.balance}")
print(f"Buying Power: ${account.buying_power}")

# List available markets
markets = client.list_markets(status='open', limit=10)
for market in markets:
    print(f"{market.title}: {market.outcomes}")

import { XOClient } from '@xo-trade/sdk';

const client = new XOClient({
  apiKey: 'pk_live_your_key',
  apiSecret: 'sk_live_your_secret'
});

// Get account info
const account = await client.getAccount();
console.log(`Balance: $${account.balance}`);

// List available markets
const markets = await client.listMarkets({ status: 'open', limit: 10 });
markets.forEach(m => console.log(`${m.title}: ${m.outcomes}`));

Authentication

All API requests require authentication via your API credentials. XO Markets uses HMAC-SHA256 signatures for secure request authentication.

Required Headers

Signature Generation

import hmac
import hashlib
import time

def generate_signature(secret_key, timestamp, method, path, body=''):
    message = f"{timestamp}{method}{path}{body}"
    signature = hmac.new(
        secret_key.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return signature

Core Concepts

Markets

A market represents a question about a future event. Each market has:

• Market ID: Unique identifier (e.g., us-election-2028)
• Title: Human-readable question
• Category: Classification (politics, finance, sports, etc.)
• Status: Current state (open, closed, resolved)
• Resolution Date: When the market will be resolved
• Outcomes: Possible results

Outcomes

An outcome is a possible result of a market:

• Outcome ID: Unique identifier (e.g., vance, newsom)
• Name: Display name (e.g., "JD Vance")
• Price: Current probability (0.00 to 1.00)
• Volume: Total trading volume in USD

Positions

A position represents your holdings in a specific outcome:

• Long Position: You own shares that pay $1 if the outcome occurs
• Short Position: You've sold shares and owe $1 if the outcome occurs

Orders

An order is an instruction to buy or sell shares:

API Reference

Account

Get Account

Retrieve account information including balance and buying power.

{
  "id": "acc_8a9b2c3d",
  "email": "trader@example.com",
  "status": "active",
  "balance": 10000.00,
  "buying_power": 8500.00,
  "pending_orders_value": 1500.00,
  "realized_pnl": 2340.50,
  "unrealized_pnl": -150.00,
  "created_at": "2024-01-15T10:30:00Z"
}

Markets

List Markets

Retrieve available prediction markets.

Query Parameters

{
  "markets": [
    {
      "id": "us-election-2028",
      "title": "Who will win the 2028 US Presidential Election?",
      "category": "politics",
      "status": "open",
      "volume_24h": 1250000.00,
      "total_volume": 45000000.00,
      "outcomes": [
        { "id": "vance", "name": "JD Vance", "price": 0.35 },
        { "id": "newsom", "name": "Gavin Newsom", "price": 0.28 },
        { "id": "other", "name": "Other", "price": 0.37 }
      ]
    }
  ],
  "next_cursor": "eyJpZCI6InVzLWVsZWN0aW9uLTIwMjgifQ=="
}

Get Market

Get Order Book

Orders

Place Order

Submit a new order.

{
  "market_id": "us-election-2028",
  "outcome_id": "vance",
  "side": "buy",
  "type": "limit",
  "amount_usd": 5000.00,
  "limit_price": 0.35,
  "time_in_force": "GTC",
  "client_order_id": "my-order-123"
}

Parameters

List Orders

Cancel Order

Positions

List Positions

{
  "positions": [
    {
      "market_id": "us-election-2028",
      "market_title": "Who will win the 2028 US Presidential Election?",
      "outcome_id": "vance",
      "outcome_name": "JD Vance",
      "side": "long",
      "qty": 14285.71,
      "avg_entry_price": 0.35,
      "current_price": 0.38,
      "market_value": 5428.57,
      "cost_basis": 5000.00,
      "unrealized_pnl": 428.57,
      "unrealized_pnl_percent": 8.57
    }
  ]
}

Close Position

WebSocket Streaming

XO Markets provides real-time streaming data via WebSocket connections.

Connection

wss://stream.xotrade.co/v1

Subscribe to Market Data

{
  "action": "subscribe",
  "channel": "market",
  "market_id": "us-election-2028"
}

Python Example

import asyncio
from xo_trade import XO

async def main():
    client = XO.Client('pk_live_your_key', 'sk_live_your_secret')
    
    async def on_price(data):
        print(f"{data['outcome_id']}: {data['price']:.2%}")
    
    # Subscribe to market prices
    await client.stream.subscribe('market', 'us-election-2028', on_price)
    
    # Keep connection alive
    await client.stream.run_forever()

asyncio.run(main())

Sandbox Environment

Use the sandbox environment for development and testing without risking real funds.

Sandbox Features

• Paper Money: Start with $100,000 in virtual funds
• Real Market Data: Live prices from production markets
• Full API Parity: All endpoints work identically to production
• Resettable: Reset your sandbox account at any time

SDKs & Tools

Official SDKs

Community Libraries

• Go: github.com/xo-trade/go-sdk
• Rust: xo-trade (crates.io)
• Java: com.xotrade:sdk

Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1699900060

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient buying power for this order",
    "details": {
      "required": 5000.00,
      "available": 2500.00
    }
  },
  "request_id": "req_a1b2c3d4"
}

FAQ

General

What are prediction markets?

Prediction markets are exchange-traded markets where participants buy and sell shares based on the outcome of future events. Share prices reflect the market's collective probability estimate.

How do payouts work?

Each share pays $1 if the outcome occurs, $0 otherwise. If you buy "Yes" shares at $0.35 and the outcome happens, you receive $1 per share (profit of $0.65/share).

Trading

What are the trading hours?

Markets are open 24/7, 365 days a year. Individual markets may close before their resolution date.

What's the minimum order size?

The minimum order is $1.00 USD.

Are there trading fees?

XO Markets charges no commission on trades. There is a small spread built into market prices.

Technical

What's the API latency?

Median order execution latency is under 50ms. WebSocket updates are delivered within 10ms of market changes.