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:

Settlement & Market Resolution

XO Markets uses the UMA Optimistic Oracle for decentralized, manipulation-resistant market resolution. This is the same oracle infrastructure used by Polymarket.

How Settlement Works

1. Market Close: Trading halts at the scheduled resolution time.
2. Oracle Request: XO submits a resolution request to the UMA Optimistic Oracle with the market question and resolution criteria.
3. Assertion Period: A proposer asserts the outcome (e.g., "Yes" or "Candidate A won"). This assertion is bonded with collateral.
4. Dispute Window: During the liveness period (typically 2-24 hours), anyone can dispute the proposed outcome by posting a counter-bond.
5. Resolution: If undisputed, the assertion is accepted. If disputed, the claim escalates to UMA's Data Verification Mechanism (DVM) where UMA token holders vote.
6. Payout: Winning shares pay $1.00; losing shares pay $0.00. Funds are credited to account balances.

Third-Party Validation for High-Value Markets

For markets with total notional exposure exceeding $100 million USD at settlement, XO requires additional independent verification:

• A recognized third-party auditor (e.g., PricewaterhouseCoopers, Deloitte) independently verifies the market outcome before final settlement.
• This dual-validation process provides an additional safeguard against oracle manipulation on high-stakes markets.
• The third-party attestation is published and linked in the settlement record.

Settlement Statuses

Dispute Handling

If an oracle outcome is disputed:

1. The dispute is escalated to UMA's DVM for a token-holder vote.
2. Voting occurs over 48-96 hours using a commit-reveal scheme.
3. The majority vote determines the final outcome.
4. Incorrect proposers/disputers lose their bonds; correct parties are rewarded.

Markets may be cancelled if the resolution criteria become ambiguous or the underlying event is invalidated.

Trading & Settlement Architecture

XO Markets operates a Central Limit Order Book (CLOB) matching engine with on-chain settlement via ERC-1155 conditional token contracts—the same architectural pattern used by Polymarket.

CLOB Matching Engine

• Order Entry: Submit orders via REST API, WebSocket, or FIX 4.4 protocol.
• Matching: Price-time priority matching with sub-50ms latency.
• Order Types: Market, limit, GTC, IOC, FOK.
• Market Data: Real-time Level 2 order book depth via WebSocket.

ERC-1155 Settlement Layer

Each market outcome is represented as an ERC-1155 token. When you buy "Yes" shares on a market, you receive ERC-1155 tokens representing that position.

End-to-End Trade Lifecycle

1. Order Submission: Client sends order via REST/WebSocket/FIX.
2. CLOB Matching: Engine matches against resting orders.
3. Trade Creation: Matched orders generate trade records.
4. Ledger Update: Internal balances updated immediately.
5. On-Chain Settlement: Trades batched and written to ERC-1155 contract.
6. Market Resolution: UMA oracle (+ third-party for >$100M) determines outcome.
7. Redemption: Winning tokens redeemed for $1.00 per share.

On-Chain Provenance

XO surfaces on-chain settlement data via API responses. Integrators do not need to interact directly with smart contracts.

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

Settlement

Get Settlement Status

Retrieve the settlement status and oracle metadata for a market.

{
  "market_id": "us-election-2028",
  "status": "resolved",
  "final_outcome_id": "vance",
  "final_outcome_name": "JD Vance",
  "resolution_timestamp": "2028-11-09T04:30:00Z",
  "oracle": {
    "provider": "uma",
    "request_id": "0x7a8b9c...",
    "assertion_timestamp": "2028-11-09T02:00:00Z",
    "liveness_period_hours": 2,
    "dispute_status": "none",
    "resolved_at": "2028-11-09T04:00:00Z"
  },
  "third_party_validation": {
    "required": true,
    "threshold_usd": 100000000,
    "market_notional_usd": 245000000,
    "provider": "PricewaterhouseCoopers",
    "status": "verified",
    "attestation_url": "https://xotrade.co/attestations/us-election-2028.pdf",
    "verified_at": "2028-11-09T04:30:00Z"
  },
  "on_chain": {
    "chain_id": 137,
    "contract_address": "0x4D97...",
    "resolution_tx_hash": "0xabc123...",
    "block_number": 98765432
  },
  "payout": {
    "winning_payout_per_share": 1.00,
    "losing_payout_per_share": 0.00,
    "total_payout_usd": 122500000
  }
}

Response Fields

Get Settlement History

Query Parameters

Trades

Retrieve executed trade data for reconciliation and audit purposes.

List Trades

Retrieve your executed trades.

Query Parameters

{
  "trades": [
    {
      "trade_id": "trd_8a7b6c5d",
      "order_id": "ord_992837",
      "market_id": "us-election-2028",
      "outcome_id": "vance",
      "side": "buy",
      "price": 0.35,
      "qty": 14285.71,
      "notional_usd": 5000.00,
      "fee_usd": 0.00,
      "maker_taker": "taker",
      "executed_at": "2024-12-01T09:15:00.456Z",
      "on_chain": {
        "tx_hash": "0xdef456...",
        "block_number": 98765400,
        "log_index": 23
      },
      "timestamps": {
        "gateway_received_at": "2024-12-01T09:15:00.012Z",
        "exchange_timestamp": "2024-12-01T09:15:00.015Z",
        "match_timestamp": "2024-12-01T09:15:00.018Z"
      }
    }
  ],
  "next_cursor": "..."
}

Response Fields

Get Market Trades (Public)

Audit Log

Access the institutional-grade audit log for compliance and reconciliation. All orders, trades, transfers, and account events are captured in an append-only, tamper-evident log.

List Audit Events

Query Parameters

{
  "events": [
    {
      "event_id": "evt_a1b2c3d4",
      "sequence": 9827364,
      "timestamp": "2024-12-01T09:15:00.456Z",
      "account_id": "acc_8a9b2c3d",
      "event_type": "order_filled",
      "entity_type": "order",
      "entity_id": "ord_992837",
      "data": {
        "market_id": "us-election-2028",
        "outcome_id": "vance",
        "side": "buy",
        "fill_price": 0.35,
        "fill_qty": 14285.71,
        "maker_taker": "taker",
        "trade_id": "trd_8a7b6c5d"
      },
      "on_chain": {
        "tx_hash": "0xdef456...",
        "block_number": 98765400
      }
    }
  ],
  "next_cursor": "..."
}

Event Types

Sub-Accounts

Manage sub-accounts under a master/omnibus account. Ideal for retail brokers managing end-user accounts.

Create Sub-Account

{
  "external_id": "user_12345",
  "label": "John Doe",
  "metadata": {
    "tier": "standard",
    "region": "US"
  }
}

{
  "sub_account_id": "sub_a1b2c3d4",
  "external_id": "user_12345",
  "label": "John Doe",
  "balance": 0.00,
  "buying_power": 0.00,
  "status": "active",
  "created_at": "2024-12-01T10:00:00Z"
}

List Sub-Accounts

Get Sub-Account

Placing Orders for Sub-Accounts

Include the sub_account_id parameter when placing orders:

{
  "market_id": "us-election-2028",
  "outcome_id": "vance",
  "side": "buy",
  "type": "limit",
  "amount_usd": 500.00,
  "limit_price": 0.35,
  "sub_account_id": "sub_a1b2c3d4"
}

Historical Market Data

Access historical price and volume data for charting and analysis.

Get Candlestick Data (OHLCV)

Query Parameters

{
  "market_id": "us-election-2028",
  "outcome_id": "vance",
  "interval": "1h",
  "candles": [
    {
      "timestamp": "2024-12-01T09:00:00Z",
      "open": 0.34,
      "high": 0.36,
      "low": 0.33,
      "close": 0.35,
      "volume": 125000.00,
      "trade_count": 847
    }
  ]
}

Get Historical Prices

Idempotency

XO Markets supports idempotent requests to safely retry operations without risk of duplicate execution.

Using Idempotency Keys

Include the Idempotency-Key header on any POST request:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Behavior

Best Practices

• Use UUID v4 for idempotency keys
• Generate a new key for each distinct operation
• Keys are valid for 24 hours
• Store the key until you receive a successful response

FIX Protocol

XO Markets supports FIX 4.4 for institutional order entry and market data. FIX is available for Enterprise tier customers.

Connection Details

Session Configuration

Supported Message Types

Inbound Messages

Outbound Messages

Custom Tags

Market Maker Features

Cancel All / Kill Switch

Rapidly cancel orders or halt trading in emergency situations.

Cancel All Orders

Cancel all open orders with optional filters for market_id, side, or outcome_id.

{
  "cancelled_count": 47,
  "cancelled_order_ids": ["ord_001", "ord_002"],
  "cancelled_at": "2024-12-01T09:15:00.123Z"
}

Activate Kill Switch

Immediately cancel all open orders and prevent new order entry until reset.

Reset Kill Switch

Self-Match Prevention (SMP)

Prevent your orders from executing against each other to avoid wash trading.

Configuration

Assign an smp_group to orders that should not match against each other:

{
  "market_id": "us-election-2028",
  "outcome_id": "vance",
  "side": "buy",
  "type": "limit",
  "amount_usd": 5000.00,
  "limit_price": 0.35,
  "smp_group": "desk_alpha",
  "smp_mode": "cancel_newest"
}

SMP Modes

Latency & Timestamps

XO provides detailed timestamps for latency analysis and trade reconciliation.

Timestamp Fields

Calculating Latency

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"
}

Settlement Updates

Subscribe to real-time settlement status changes:

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

{
  "type": "settlement",
  "market_id": "us-election-2028",
  "status": "resolved",
  "previous_status": "pending_third_party",
  "final_outcome_id": "vance",
  "final_outcome_name": "JD Vance",
  "oracle": {
    "provider": "uma",
    "request_id": "0x7a8b9c...",
    "resolved_at": "2028-11-09T04:00:00Z"
  },
  "third_party_validation": {
    "provider": "PricewaterhouseCoopers",
    "status": "verified"
  },
  "on_chain": {
    "tx_hash": "0xabc123...",
    "block_number": 98765432
  },
  "timestamp": "2028-11-09T04:30:00.123Z"
}

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.

Do you support FIX protocol?

Yes, FIX 4.4 is available for Enterprise tier customers. We support NewOrderSingle (D), OrderCancelRequest (F), OrderCancelReplaceRequest (G), and full market data streaming. See the FIX Protocol section for the complete specification.

Institutional

How are markets settled?

XO uses the UMA Optimistic Oracle for decentralized market resolution. For markets exceeding $100M in total notional at settlement, we additionally require third-party validation from recognized auditors (e.g., PricewaterhouseCoopers). See Settlement & Market Resolution for details.

How do sub-accounts work?

Retail brokers and trading apps can manage end-user accounts via our sub-account API. Create sub-accounts under your master account, then specify sub_account_id on orders to track positions and P&L separately per user. See Sub-Accounts for the full API reference.

How can we access audit logs?

The /v1/audit/logs endpoint provides an append-only, tamper-evident log of all account activity including orders, fills, transfers, and settlements. Logs include on-chain transaction references for reconciliation. Data is retained for 7 years.

Do you support self-match prevention?

Yes. Assign an smp_group to orders that should not execute against each other. Supported modes include cancel_newest, cancel_oldest, cancel_both, and decrement_and_cancel. See Market Maker Features.