Betfair

Founded in 2000, Betfair operates the world’s largest online betting exchange, with its headquarters in London and satellite offices across the globe.

NautilusTrader provides an adapter for integrating with the Betfair REST API and Exchange Streaming API.

Installation

Install NautilusTrader with Betfair support:

uv pip install "nautilus_trader[betfair]"

To build from source with Betfair extras:

uv sync --all-extras

Examples

You can find live example scripts here.

Betfair documentation

Betfair provides documentation for developers:

• Betfair Developer Portal: Main entry point for API access and documentation.
• Exchange API Guide: Overview of the Betting, Accounts, and Streaming APIs.

Application keys

Betfair requires an Application Key to authenticate API requests. After registering and funding your account, obtain your key using the API-NG Developer AppKeys Tool.

Two App Keys are assigned per account: a Live key (requires a one-time activation fee) and a Delayed key for development and testing.

API credentials

Supply your Betfair credentials via environment variables or client configuration:

export BETFAIR_USERNAME=<your_username>
export BETFAIR_PASSWORD=<your_password>
export BETFAIR_APP_KEY=<your_app_key>
export BETFAIR_CERTS_DIR=<path_to_certificate_dir>

SSL Certificates

Betfair recommends non-interactive (bot) login with SSL certificates for automated trading systems. The certs_dir configuration is optional, but certificates are recommended for production deployments.

Generating certificates

Create a 2048-bit RSA certificate using OpenSSL:

# Generate private key and certificate signing request
openssl genrsa -out client-2048.key 2048
openssl req -new -key client-2048.key -out client-2048.csr

# Self-sign the certificate (valid for 365 days)
openssl x509 -req -days 365 -in client-2048.csr -signkey client-2048.key -out client-2048.crt

Uploading to Betfair

Before using the certificate, attach it to your Betfair account:

1. Navigate to My Betfair Account Security.
2. Scroll to Automated Betting Program Access and click Edit.
3. Upload your client-2048.crt file.

Directory structure

Place your certificate files in a directory and set BETFAIR_CERTS_DIR to that path:

/path/to/certs/
├── client-2048.crt
└── client-2048.key

Overview

The Betfair adapter provides three primary components:

• BetfairInstrumentProvider: loads Betfair markets and converts them into Nautilus instruments.
• BetfairDataClient: streams real-time market data from the Exchange Streaming API.
• BetfairExecutionClient: submits orders (bets) and tracks execution status via the REST API.

Orders capability

Betfair operates as a betting exchange with unique characteristics compared to traditional financial exchanges:

Order types

Execution instructions

Time in force options

Advanced order features

Batch operations

Position management

Order querying

Contingent orders

Tick scheme and pricing

Betfair uses a tiered tick scheme with varying increments across price ranges:

The minimum price is 1.01 and the maximum is 1000.00.

Order modification

Order modification on Betfair has specific constraints:

• Price and size cannot be changed atomically - these require separate operations.
• Price modification uses ReplaceOrders (cancel + new order at new price).
• Size reduction uses CancelOrders with a size_reduction parameter.
• Size increase is not supported - submit a new order instead.

Order stream fill handling

The execution client processes order updates from the Betfair Exchange Streaming API. Two configuration options control how updates are filtered:

• stream_market_ids_filter: Filters at the market level (early exit, silent skip).
• ignore_external_orders: Filters at the order level (controls warning vs debug logging).

Note that stream_market_ids_filter is independent of reconciliation scope (reconcile_market_ids_only). Stream filtering affects live updates only; reconciliation uses its own market filter.

The same stream_market_ids_filter is also applied during full-image reconciliation in check_cache_against_order_image.

When ignore_external_orders=True, the client silently skips orders and fills not found in cache:

Fill handling

The adapter handles several edge cases when processing fills from the stream:

• Incremental fills: Betfair reports cumulative matched sizes. The adapter calculates incremental fills by tracking the last known filled quantity per order.
• Overfill protection: Fills that would exceed the order quantity are rejected.
• Deduplication: A cache of published trade IDs prevents duplicate fill events from late messages or stream reconnection replays.
• Race conditions: When stream fills arrive before the HTTP order response, the adapter caches the venue order ID immediately to ensure correct order matching.
• Network error recovery: When an HTTP order submission fails with a network error (timeout, connection reset), the order may still have been placed on the venue. The adapter leaves the order in SUBMITTED status and retains the customer order reference so the stream can confirm the order when it reconnects. API errors (where Betfair explicitly rejected) still reject immediately.

Rate limiting

The adapter uses separate rate limit buckets so that account state polling and reconciliation do not throttle order placement:

Order status and fill report queries retry once on TOO_MANY_REQUESTS errors after a 1-second delay; order operations reject with the error message.

Betfair's actual API limits are more nuanced:

Custom data types

The Betfair adapter provides several custom data types that flow through the market stream. All custom data is delivered automatically when subscribed to markets - no explicit subscription is required, though strategies can register handlers for specific data types.

BetfairTicker

Real-time ticker data for a betting selection.

BetfairStartingPrice

The realized Betfair Starting Price (BSP) after market close.

BetfairRaceRunnerData

Live GPS tracking data for individual horses (Total Performance Data). Available for supported UK and Irish races.

BetfairRaceProgress

Race summary data with sectional times and running order.

Subscribing to custom data

Custom data flows automatically through the Betfair market stream when you subscribe to markets. To receive custom data in your strategy or actor, register a handler with the Betfair client ID:

from nautilus_trader.adapters.betfair.constants import BETFAIR_CLIENT_ID
from nautilus_trader.adapters.betfair.data_types import BetfairRaceRunnerData
from nautilus_trader.adapters.betfair.data_types import BetfairRaceProgress
from nautilus_trader.adapters.betfair.data_types import BetfairTicker
from nautilus_trader.model.data import DataType

class MyStrategy(Strategy):
    def on_start(self):
        # Subscribe to ticker data
        self.subscribe_data(DataType(BetfairTicker), client_id=BETFAIR_CLIENT_ID)

        # Subscribe to ALL race runner data (wildcard)
        self.subscribe_data(DataType(BetfairRaceRunnerData), client_id=BETFAIR_CLIENT_ID)

        # Or subscribe to a specific runner by selection_id
        self.subscribe_data(
            DataType(BetfairRaceRunnerData, metadata={"selection_id": 49411491}),
            client_id=BETFAIR_CLIENT_ID,
        )

        # Subscribe to ALL race progress updates (wildcard)
        self.subscribe_data(DataType(BetfairRaceProgress), client_id=BETFAIR_CLIENT_ID)

        # Or subscribe to a specific race by race_id
        self.subscribe_data(
            DataType(BetfairRaceProgress, metadata={"race_id": "35278018.1617"}),
            client_id=BETFAIR_CLIENT_ID,
        )

    def on_data(self, data):
        if isinstance(data, BetfairRaceRunnerData):
            self.log.info(
                f"Runner {data.selection_id}: speed={data.speed} m/s, "
                f"progress={data.progress}m to finish"
            )
        elif isinstance(data, BetfairRaceProgress):
            self.log.info(f"Race order: {data.order}")
        elif isinstance(data, BetfairTicker):
            self.log.info(f"LTP: {data.last_traded_price}")

Loading race data from files

For backtesting with recorded race data, use the file parser:

from nautilus_trader.adapters.betfair.parsing.core import parse_betfair_rcm_file

for data in parse_betfair_rcm_file("path/to/rcm_data.json"):
    if isinstance(data, BetfairRaceRunnerData):
        print(f"Runner {data.selection_id} at {data.latitude}, {data.longitude}")

Configuration

Data client configuration options

Execution client configuration options

Session management

Betfair sessions typically expire every 12-24 hours. The adapter automatically handles session reconnection when NO_SESSION or INVALID_SESSION_INFORMATION errors occur:

• The HTTP client reconnects and obtains a new session token.
• The streaming client re-authenticates and resubscribes to markets.
• The keep-alive mechanism (keep_alive_secs, default 10 hours) proactively extends sessions.

Market version price protection

Betfair markets have a version number that increments whenever the market book changes (e.g., a new price level appears, a bet is matched). The adapter can attach this version to placeOrders and replaceOrders requests, providing price protection against stale orders.

When use_market_version=True, each order request includes the market version last seen by the adapter. If the market has advanced beyond that version by the time Betfair processes the order, Betfair lapses the bet rather than matching it against a changed book.

from nautilus_trader.adapters.betfair.config import BetfairExecClientConfig

exec_config = BetfairExecClientConfig(
    account_currency="GBP",
    use_market_version=True,
)

The adapter reads the market version from the instrument's info dictionary, which the Exchange Streaming API's MarketDefinition updates populate. This means:

• The version reflects the most recent stream update, not the HTTP API snapshot.
• There is inherent latency between a market change and the adapter receiving the updated version.
• Orders submitted before the first stream MarketDefinition is received will not include a version.

Multi-node deployment

When multiple trading nodes share a single Betfair account across different markets, configure each node to avoid interference:

1. Set stream_market_ids_filter to include only that node's markets.
2. Set ignore_external_orders=True to suppress warnings about orders from other nodes.
3. Set reconcile_market_ids_only=True to limit reconciliation scope.

This prevents warning spam and ensures each node processes only its own orders and fills.

Here is a minimal example showing how to configure a live TradingNode with Betfair clients:

from nautilus_trader.adapters.betfair import BETFAIR
from nautilus_trader.adapters.betfair import BetfairLiveDataClientFactory
from nautilus_trader.adapters.betfair import BetfairLiveExecClientFactory
from nautilus_trader.config import TradingNodeConfig
from nautilus_trader.live.node import TradingNode

# Configure Betfair data and execution clients (using AUD account currency)
config = TradingNodeConfig(
    data_clients={BETFAIR: {"account_currency": "AUD"}},
    exec_clients={BETFAIR: {"account_currency": "AUD"}},
)

# Build the TradingNode with Betfair adapter factories
node = TradingNode(config)
node.add_data_client_factory(BETFAIR, BetfairLiveDataClientFactory)
node.add_exec_client_factory(BETFAIR, BetfairLiveExecClientFactory)
node.build()

Contributing