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.

:::info See the Application Keys documentation for detailed setup instructions. :::

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>

:::tip We recommend using environment variables to manage your credentials. :::

:::note Current Rust note: Rust currently reads BETFAIR_USERNAME, BETFAIR_PASSWORD, and BETFAIR_APP_KEY. It does not yet read BETFAIR_CERTS_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

:::info SSL certificates are used for the Exchange Streaming API connection. The REST API uses username/password authentication with your Application Key. :::

:::warning Enabling 2-Step Authentication on the Betfair website does not affect API access. Certificate-based login remains functional regardless of 2FA settings. :::

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.

Implementation status

NautilusTrader currently ships a stable Python Betfair adapter and an in-progress Rust parity path.

This page remains the stable guide. It now calls out the main Rust differences inline. Use the Betfair v2 transition guide for the current Rust-first behavior in crates/adapters/betfair and for the planned cutover path.

Orders capability

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

Order types

Execution instructions

Time in force options

:::note Betfair uses a persistence model rather than traditional time-in-force. The adapter maps FOK to Betfair's FILL_OR_KILL, while IOC uses FILL_OR_KILL with min_fill_size=0 to allow partial fills.

The current adapters also support BSP on-close order flows. Rust only accepts MARKET orders in AT_THE_CLOSE mode. Rust also maps LIMIT orders in AT_THE_CLOSE or AT_THE_OPEN mode to Betfair LIMIT_ON_CLOSE instructions. :::

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.

:::warning A replace operation generates both a cancel event for the original order and an accepted event for the replacement order. The adapter tracks pending replacements to suppress synthetic cancel events. :::

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. Python also uses it to control the log level for full-image cache checks. Rust currently only skips OCM updates with no rfo.

The flowchart below matches the stable Python execution path.

Python keeps stream_market_ids_filter separate from reconciliation scope (reconcile_market_ids_only). Rust currently falls back to stream_market_ids_filter during reconciliation when reconcile_market_ids_only=False and no explicit reconcile_market_ids are configured.

flowchart TD
    A[Stream update arrives] --> B{Market in
stream_market_ids_filter?}
    B -->|No filter set| C{Instrument loaded?}
    B -->|Yes| C
    B -->|No| D[Skip silently]
    C -->|No| E[Warning: Instrument not loaded]
    C -->|Yes| F{Known order?
rfo or cache}
    F -->|Yes| G[Process order update]
    F -->|No| H{ignore_external_orders?}
    H -->|True| I[Debug log, skip]
    H -->|False| J[Warning log, skip]

Python also applies stream_market_ids_filter during full-image reconciliation in check_cache_against_order_image. Rust currently reconciles through generate_mass_status() and does not yet perform the same full-image cache check.

When ignore_external_orders=True, the Python adapter skips orders and fills not found in cache:

:::info For multi-node setups sharing a Betfair account, set both stream_market_ids_filter (your markets only) and ignore_external_orders=True to avoid warnings about orders managed by other nodes. :::

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:

:::info For details on rate limits, see Why am I receiving the TOO_MANY_REQUESTS error? and Market Data Request Limits. :::

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

:::info Subscribing with DataType(BetfairRaceRunnerData) (no metadata) receives data for all runners. Adding metadata={"selection_id": <id>} filters to a specific runner. Similarly, DataType(BetfairRaceProgress) receives progress for all races, while metadata={"race_id": <id>} filters to a specific race.

Race data (RCM messages) requires Total Performance Data (TPD) coverage and a Betfair API key with TPD access. Not all races have GPS tracking enabled. :::

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

:::warning When stream_conflate_ms is None, Betfair applies its default conflation behavior (typically enabled). Set stream_conflate_ms=0 explicitly to guarantee no conflation and receive every price update. :::

:::note Current Rust differences:

• Rust does not yet expose certs_dir.
• Rust does not use instrument_config; it scopes instruments with direct filter fields on BetfairDataConfig.
• Rust uses a fixed 36,000 second keep-alive interval.
• Rust currently requires stream_heartbeat_ms; it does not accept None to omit the heartbeat.

:::

Execution client configuration options

:::warning If you set stream_market_ids_filter, ensure it includes all markets you trade. Orders placed on markets excluded from this filter will miss live fill and cancel updates from the stream. :::

:::note Current Rust differences:

• Rust does not yet expose certs_dir or instrument_config.
• Rust uses calculate_account_state as the gate for periodic account-state polling.
• Rust uses reconcile_market_ids when reconcile_market_ids_only=True.
• If reconcile_market_ids_only=False, Rust currently falls back to stream_market_ids_filter for startup reconciliation when reconcile_market_ids is unset.
• Rust currently applies ignore_external_orders only to OCM updates with no rfo.
• Rust currently requires stream_heartbeat_ms; it does not accept None to omit the heartbeat.

:::

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 proactively extends sessions. Python exposes keep_alive_secs. Rust currently uses a fixed 10-hour interval.

:::info Session errors during account state polling or keep-alive trigger automatic reconnection. No manual intervention is required for normal session expiry. :::

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.

:::warning Market version protection is conservative. In fast-moving markets, the version may advance between your order signal and submission, causing the bet to lapse even though the price is still acceptable. Consider this trade-off between protection and fill rate. :::

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

:::info For additional features or to contribute to the Betfair adapter, please see our contributing guide. :::