Getting Started with Copilot

The Complete Guide

What you'll learn: What Copilot is, how to set up your trading configurations, how to ingest odds and scores into your system, and how to use every Copilot endpoint. This guide is designed for technical and non-technical team members alike.

What Is Copilot?

Copilot is OpticOdds' automated trading solution that enables sportsbook operators to generate custom odds efficiently and at scale. Instead of manually sourcing and managing odds from individual sportsbooks, Copilot lets you define your pricing rules once and generates fair-value odds automatically — across every sport, league, and market you configure.

In plain terms: You tell Copilot which sportsbooks to pull from, how to weight them, what margin (vig) to apply, and which markets you care about. Copilot then delivers a continuous stream of custom-priced odds to your platform — in real time.

What Copilot Gives You

• Real-time data integration — Live odds powered by your chosen sportsbook sources
• Customizable markets — Full control over which sports, leagues, and market types you offer
• Automated market settlement — Bets are graded automatically (Won, Lost, Refunded)
• Odds suspension control — Markets lock automatically when conditions are met (e.g., odds go out of range)
• Multiple ingestion methods — REST polling, SSE streaming, or RabbitMQ queues
• Same Game Parlay pricing — SGP/Bet Builder powered by your configurations
• Historical odds tracking — Full audit trail of every price change, lock, and settlement
• Live scores — Real-time score data integrated alongside your odds

How Copilot Works — The Big Picture

Here's the workflow from setup to live odds:

1. Set Default Settings     → Global defaults for vig, odds range, min difference
2. Create Configurations    → Per-sport/league rules (sportsbooks, weightings, markets)
3. Copilot Generates Odds   → AlgoOdds engine produces your custom-priced odds
4. Ingest the Data          → Pull odds into your system via REST, SSE, or RabbitMQ
5. Display & Accept Bets    → Show odds to your users, accept wagers
6. Grade & Settle           → Copilot automatically grades bets when games complete

Step 1: Prerequisites

Before setting up Copilot, make sure you have:

• An OpticOdds API license key (contact OpticOdds to get access)
• Familiarity with OpticOdds core resources — complete the Odds API Getting Started Guide through Step 4 first
• Access to the OpticOdds App at app.opticodds.com — this is where you configure Copilot

Authentication

All Copilot API calls use the same authentication as the standard API:

Option A: Header (recommended)

curl --location 'https://api.opticodds.com/api/v3/copilot/fixtures/odds?fixture_id=032B6289DB25' \
  --header 'X-Api-Key: YOUR_API_KEY'

Option B: Query Parameter

curl 'https://api.opticodds.com/api/v3/copilot/fixtures/odds?fixture_id=032B6289DB25&key=YOUR_API_KEY'

Step 2: Default Settings

Where: OpticOdds App → Copilot → Settings Docs: Default Settings

Default Settings are the global baseline for all future configurations you create. Any new configuration will inherit these values unless you override them. Think of these as your company-wide trading defaults.

There are three settings:

Min Difference

What it does: Sets the minimum change in odds (in probability format) required before Copilot publishes an update.

Why it matters: Without this, your odds would fluctuate constantly with every tiny movement in the underlying sportsbook lines. This setting gives your users more stable pricing — the price won't oscillate back and forth on small changes.

How it works:

abs(old_price − new_price) >= min_difference

Both old_price and new_price are in probability format. For example, +100 = 50%, -200 = 66.7%, etc.

Example: If Min Difference is set to 2, and your current price implies 52% probability, the price won't update until the new weighted average moves to at least 54% or below 50%.

Default Min - Max Odds Range

What it does: Sets the floor and ceiling for the odds Copilot will display. You configure what happens when the weighted price crosses these thresholds (covered in the Configurations section below).

Example: If you set Min = -10,000 and Max = +10,000, any weighted prices beyond those limits will be handled based on your configuration rules.

Default Vig

What it does: Sets the default margin (vig/hold) applied to the weighted prices.

Important: This only applies when your configurations are set to Devig Odds mode. If you use Average Odds mode, this setting has no effect.

Example: If you set Default Vig to 4, a 4% margin is applied on top of the devigged prices.

Step 3: Create Configurations

Where: OpticOdds App → Copilot → Configurations Docs: Configurations

Configurations are the heart of Copilot. Each configuration defines the pricing rules for a specific sport + league + market combination. You can create as many configurations as you need.

Creating a configuration is a two-step process:

Step 3a: Configuration Settings

When you click Add Configuration, you'll walk through 8 settings:

1. Select a Sport & Leagues

Choose one sport and at least one league per configuration.

Example: Sport = Basketball, Leagues = NBA, NCAAB, Euroleague

You can't mix sports in a single configuration. Create separate configurations for NFL, NBA, MLB, etc.

2. Choose Markets

Select which market types this configuration should generate odds for. Clicking a section header selects all markets in that group.

Available market types include: Point Spread, Moneyline, Total Points, Team Totals, Player Props (Points, Rebounds, Assists, Hits, Strikeouts, etc.), 1st Half lines, 1st Quarter lines, and many more.

3. Choose Game Status

Define whether this configuration applies to:

• Pre-match — Games that haven't started yet
• Live — Games currently in play
• Both — Pre-match and live

You might want different sportsbook weightings or vig for live vs. pre-match odds. Create separate configurations for each if needed.

4. Consensus Split

This is where you define which sportsbooks feed into your pricing and how much weight each one carries. The weights must add up to 100%.

Example configuration:

Key concepts:

• Mandatory (🔑 icon): Marking a sportsbook as mandatory means that book must have odds for a market/selection in order for Copilot to return data. If the mandatory book doesn't have it, no odds are generated for that selection.

• Minimum Providers: The minimum number of sportsbooks from your list that must have lines available before Copilot generates odds. We recommend setting this to at least 2 to prevent issues with stale lines or a single sportsbook having incorrect data.

• Dynamic Reweighting: If a non-mandatory sportsbook is missing data, the weights are automatically redistributed among the available books. For example, if bet365 has no lines, the split becomes Suprabets 75% / 1XBet 25%.

• Algo Mode: Toggle this on to use AlgoOdds — OpticOdds' proprietary algorithm that automatically determines optimal weightings instead of manual percentages.

5. Add Vig

Choose how you want to apply your margin:

Average Odds Takes the raw prices for each market/selection, averages them across your weighted sportsbooks, and then adds your vig on top. Simple and straightforward.

Devig Odds First removes the vig from each underlying sportsbook's prices (using the multiplicative method), averages the devigged prices, and then applies your custom vig on top. This gives you a cleaner, more accurate fair-value price before adding your own margin.

With the multiplicative method, the vigorish is spread proportionally based on each outcome's implied probability. Higher probability outcomes (favorites) receive a larger allocation of the vig.

6. Min Difference

Same concept as the Default Setting — the minimum odds change (in probability format) before an update is published. You can override the default for this specific configuration.

7. Min - Max Odds Range

Set the floor and ceiling for this configuration, and choose what happens when the weighted price goes out of range:

• Keep Price in Range — Pins the price to the nearest threshold. If the weighted price is -20,000 and your min is -10,000, the published price will be -10,000.
• Suspend — Locks the selection so it's no longer available for betting. The odd will fire a copilot-locked-odds event.

8. Name Your Configuration

Give it a descriptive name so you can find it easily in the list view.

Examples: "NBA: DraftKings 50%, FanDuel 50%", "NFL Pre-Match: Pinnacle 40%, bet365 30%, Betway 30%", "Tennis: Live Only - Devig 3%"

Step 3b: Customization (Per-Market Overrides)

After the initial settings, you can override any of the previous settings for specific markets. This lets you apply different vig, different sportsbook weightings, or different odds ranges for particular market types within the same configuration.

Example: You might want 3% vig on Moneyline but 5% vig on Player Props within the same NBA configuration. The Customization step lets you do exactly that.

Step 4: Copilot Versions

Endpoint: GET /copilot/versions Docs: /copilot/versions

Copilot supports multiple versions (environments). Each organization starts with one default version. If you need additional environments (e.g., for testing, staging, or different product lines), contact your sales rep (additional charges may apply).

Versions are useful when you want to:

• Run a test configuration alongside your live production config
• Serve different odds to different products or brands
• A/B test pricing strategies

Endpoints that support versions accept a version_id parameter:

• /copilot/fixtures/odds — filter by version
• /stream/copilot/{sport}/odds — separate stream connections per version
• /copilot/queue/start — attribute queues to a specific version

# List all your versions
curl 'https://api.opticodds.com/api/v3/copilot/versions' \
  --header 'X-Api-Key: YOUR_API_KEY'

Step 5: Ingest Odds Data

Docs: Odds Integration Guide

Once your configurations are set up and active, Copilot immediately starts generating odds. You need to ingest this data into your system. There are three methods, from simplest to most scalable:

Method 1: REST API Polling (Simple)

The easiest way to get started. Make standard GET requests to pull current odds snapshots.

Endpoint: GET /copilot/fixtures/odds

curl 'https://api.opticodds.com/api/v3/copilot/fixtures/odds?fixture_id=032B6289DB25&key=YOUR_API_KEY'

Key parameters:

Example Response:

{
  "data": [
    {
      "id": "032B6289DB25",
      "game_id": "78014-37797-24-43",
      "start_date": "2024-10-25T00:15:00Z",
      "home_competitors": [
        {
          "id": "13AD4FDBEBA8",
          "name": "Los Angeles Rams",
          "abbreviation": "LAR",
          "logo": "https://cdn.opticodds.com/team-logos/football/99.png"
        }
      ],
      "away_competitors": [
        {
          "id": "24E4EA618C5E",
          "name": "Minnesota Vikings",
          "abbreviation": "MIN",
          "logo": "https://cdn.opticodds.com/team-logos/football/101.png"
        }
      ],
      "status": "unplayed",
      "is_live": false,
      "sport": { "id": "football", "name": "Football" },
      "league": { "id": "nfl", "name": "NFL" },
      "odds": [
        {
          "id": "1:-1:032B6289DB25:point_spread:los_angeles_rams_+2_5",
          "market": "Point Spread",
          "name": "Los Angeles Rams +2.5",
          "is_main": true,
          "selection": "Los Angeles Rams",
          "price": -101,
          "timestamp": 1729714816.49106,
          "points": 2.5,
          "player_id": null,
          "team_id": "13AD4FDBEBA8"
        }
      ]
    }
  ]
}

The id field on each odd (e.g., "1:-1:032B6289DB25:point_spread:los_angeles_rams_+2_5") is the unique identifier you'll use for grading, historical lookups, and the Copilot Parlay Pricer.

When to use polling: Great for getting started, testing, or low-frequency data needs. For production systems with real-time requirements, use SSE streaming or RabbitMQ.

Method 2: SSE Streaming (Live Updates)

Subscribe to a persistent HTTP stream and receive odds updates the moment they happen. This is the best option for live/in-play use cases.

Endpoint: GET /stream/copilot/{sport}/odds

import requests
import json
import sseclient  # pip install sseclient-py

last_entry_id = None

while True:
    try:
        params = {
            "key": "YOUR_API_KEY",
            "market": ["Moneyline"],
            "league": ["NBA"],
        }
        if last_entry_id:
            params["last_entry_id"] = last_entry_id

        r = requests.get(
            "https://api.opticodds.com/api/v3/stream/copilot/basketball/odds",
            params=params,
            stream=True,
        )
        client = sseclient.SSEClient(r)

        for event in client.events():
            if event.event == "copilot-odds":
                data = json.loads(event.data)
                last_entry_id = data.get("entry_id")
                print("Odds update:", data)
            elif event.event == "copilot-locked-odds":
                data = json.loads(event.data)
                last_entry_id = data.get("entry_id")
                print("Odds locked:", data)
            elif event.event == "copilot-settled-odds":
                data = json.loads(event.data)
                last_entry_id = data.get("entry_id")
                print("Odds settled:", data)
            else:
                print(event.event, ":", event.data)

    except Exception as ex:
        print("Disconnected, reconnecting...")

Stream event types:

Best practice: Group up to 10 leagues per connection. Use last_entry_id to resume from where you left off after a disconnect.

Method 3: RabbitMQ (Scalable Queue-Based)

The most robust option for production-grade systems. Messages are queued and you consume them at your own pace.

Step 1: Get credentials — Contact your sales rep for your rabbitmq_username and rabbitmq_password.

Step 2: Start your queue

curl -X POST 'https://api.opticodds.com/api/v3/copilot/queue/start' \
  --header 'X-Api-Key: YOUR_API_KEY'

Response:

{
  "data": [
    {
      "id": 3,
      "queue_name": "AAAAAAA_2_cop_4HOEXAMPLEQUEUE",
      "enabled": true,
      "is_live": false,
      "odds_format": "AMERICAN"
    }
  ]
}

Step 3: Connect to RabbitMQ

import pika

connection = pika.BlockingConnection(
    pika.ConnectionParameters(
        host='copilot-rmq.opticodds.com',
        port=5672,
        virtual_host='api',
        credentials=pika.PlainCredentials('<USERNAME>', '<PASSWORD>')
    )
)

def callback(ch, method, properties, body):
    print("Received:", body)

channel = connection.channel()
channel.basic_qos(prefetch_count=100)
channel.basic_consume(queue='YOUR_QUEUE_NAME', on_message_callback=callback, auto_ack=True)
channel.start_consuming()

Message types are the same as streaming: copilot-odds, copilot-locked-odds, copilot-settled-odds, and ping.

Important: If more than 10,000 unread messages accumulate, the queue is automatically cleared and deleted. Your org admins will be notified via email. You'll need to call /queue/start again to resume.

Step 6: Ingest Scores (Optional)

Docs: Scores Integration Guide

If you need live scores alongside your odds, Copilot provides a separate scores queue.

Start the scores queue:

curl -X POST 'https://api.opticodds.com/api/v3/copilot/results/queue/start' \
  --header 'X-Api-Key: YOUR_API_KEY'

The scores queue delivers fixture-results events with comprehensive data including: score by period, in-play status (period, clock, possession), player stats, and team stats.

Queue limit for scores: 1,500 unread messages (lower than the odds queue). Keep your consumer running to avoid queue deletion.

Score ingestion supports the same three methods: REST polling, SSE streaming, and RabbitMQ.

Step 7: Grade & Settle Bets

Endpoint: GET /copilot/grader/odds Docs: /copilot/grader/odds

Copilot automatically grades bets when games complete. You can query the grader to check the settlement status of any odd.

curl 'https://api.opticodds.com/api/v3/copilot/grader/odds?id=1:-1:0084DFECD1BD:1st_half_moneyline:fujian_sturgeons&key=YOUR_API_KEY'

Response:

{
  "data": [
    {
      "id": "1:-1:0084DFECD1BD:1st_half_moneyline:fujian_sturgeons",
      "status": "Lost",
      "settled_at": "2024-10-23T13:58:23.363"
    }
  ]
}

Possible settlement statuses:

Settlements also fire automatically through your streaming connection or RabbitMQ queue as copilot-settled-odds events, so you don't necessarily need to poll this endpoint.

Additional Copilot Endpoints

Get Copilot Fixtures

GET /copilot/fixtures — List all fixtures available in your Copilot data.

curl 'https://api.opticodds.com/api/v3/copilot/fixtures?sport=basketball&league=NBA&key=YOUR_API_KEY'

Supports filters for: sport, league, status, is_live, team_id, start_date_before, start_date_after, season_year, season_week, season_type, division, conference, and more.

Historical Odds

GET /copilot/fixtures/odds/historical — View the full price history of any odd, including every update, suspension, and settlement.

curl 'https://api.opticodds.com/api/v3/copilot/fixtures/odds/historical?id=1:-1:032B6289DB25:moneyline:los_angeles_rams&key=YOUR_API_KEY'

Response:

{
  "data": [
    {
      "id": "1:-1:032B6289DB25:moneyline:los_angeles_rams",
      "entries": [
        {
          "timestamp": 1755110904.696682,
          "event": "copilot-settled-odds",
          "price": 150.0,
          "is_main": true,
          "settlement": "Lost"
        },
        {
          "timestamp": 1755110840.04459,
          "event": "copilot-locked-odds",
          "price": 150.0,
          "is_main": true,
          "settlement": null
        },
        {
          "timestamp": 1755110809.451415,
          "event": "copilot-odds",
          "price": 150.0,
          "is_main": true,
          "settlement": null
        },
        {
          "timestamp": 1755110725.246358,
          "event": "copilot-odds",
          "price": 130.0,
          "is_main": true,
          "settlement": null
        }
      ]
    }
  ]
}

Pass up to 10 IDs per request. This is invaluable for auditing, reconciliation, and understanding how your prices moved over the life of a market.

Snapshot Odds

GET /copilot/snapshot/fixtures/odds — Get a point-in-time snapshot of all odds for given fixtures. Useful for bulk data pulls.

curl 'https://api.opticodds.com/api/v3/copilot/snapshot/fixtures/odds?fixture_id=032B6289DB25&key=YOUR_API_KEY'

Parlay Pricer (Bet Builder)

POST /copilot/parlay/odds — Price same game parlays using your Copilot configurations.

curl -X POST 'https://api.opticodds.com/api/v3/copilot/parlay/odds' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "entries": [
      { "id": "1:-1:032B6289DB25:moneyline:los_angeles_rams" },
      { "id": "1:-1:032B6289DB25:player_passing_yards:matthew_stafford_over_250_5" },
      { "id": "1:-1:032B6289DB25:total_points:over_44_5" }
    ]
  }'

Just pass the id of each odds entry — your configuration handles the pricing. See the SGP Pricer & Bet Builder Guide for full details.

Queue Management

Quick Reference: All Copilot Endpoints

Base URL: https://api.opticodds.com/api/v3

Odds Formats

All Copilot endpoints support multiple odds formats via the odds_format parameter:

Rate Limits

Rate limits reset after the 15-second window.

Recommended Integration Path

Here's the order we recommend for a smooth integration:

1. Complete the Odds API Getting Started Guide — Familiarize yourself with fixtures, markets, sports, and leagues (through Step 4)
2. Set your Default Settings — Configure your global defaults
3. Create your first Configuration — Start with one sport/league to test
4. Test with REST polling — Call /copilot/fixtures/odds to verify your odds are generating correctly
5. Set up streaming or RabbitMQ — Move to real-time ingestion for production via the Odds Integration Guide
6. Set up scores ingestion — Follow the Scores Integration Guide if you need live scores
7. Test the grader — Verify that completed games settle correctly via /copilot/grader/odds
8. Add more configurations — Expand to additional sports, leagues, and markets
9. Integrate the Parlay Pricer — If you need SGP pricing, use /copilot/parlay/odds

Glossary

Additional Resources

• Full Developer Docs
• Odds API Getting Started Guide
• Configurations Guide
• Default Settings
• Odds Integration Guide
• Scores Integration Guide
• API FAQ
• SGP Pricer & Bet Builder Guide
• Contact OpticOdds support for onboarding assistance