flūmine

Build Status

flumine is an open-source, event-based trading framework for sports betting, designed to simplify the development and execution of betting strategies on betting venues. flumine provides efficient handling of data streams, risk management, and execution capabilities.

docs

join betcode slack group (2.5k+ members!)

overview

Event-based Execution: Real-time execution of trading strategies based on incoming market events
Custom Strategy Implementation: Easily define and implement trading strategies
Risk Management: Integrated risk management tools to monitor and limit exposure
Modular Design: Easily extendable and customizable components
Simulation: Simulate strategies/execution using historical data
Paper Trading: Test strategies in a simulated environment before going live
Data: Support for market, order and custom streaming data
Venues: Multi venue / concurrent venue support

venues

Betfair
Betdaq
Betconnect (account/execution functionality)
Smarkets (roadmap)
Matchbook (roadmap)
Polymarket (roadmap)
Kalshi (roadmap)
BetDEX (roadmap)

Backtesting Analysis

Tested on Python 3.10, 3.11, 3.12, 3.13 and 3.14.

installation

$ pip install flumine

flumine requires Python 3.10+

setup

Get started...

import betfairlightweight
from flumine import Flumine, BaseStrategy, clients
from flumine.streams.betfairmarketstream import BetfairMarketStream
from betfairlightweight.filters import streaming_market_filter

# Define your strategy here
class ExampleStrategy(BaseStrategy):
    def check_market_book(self, market, market_book) -> bool:
        # process_market_book only executed if this returns True
        return True

    def process_market_book(self, market, market_book):
        # Your strategy logic
        pass

# Initialize your client
trading = betfairlightweight.APIClient("username")
client = clients.BetfairClient(trading)

# Initialize the framework
framework = Flumine(client)

# Add your strategy to the framework with a stream
framework.add_strategy(
    ExampleStrategy(
        stream=BetfairMarketStream(
            market_filter=streaming_market_filter(
                event_type_ids=["7"],
                country_codes=["GB"],
                market_types=["WIN"],
            ),
        )
    )
)

# Start the trading framework
framework.run()

Example strategy with logic and order execution:

import betfairlightweight
from flumine import Flumine, BaseStrategy, clients
from flumine.order.trade import Trade
from flumine.order.order import LimitOrder, OrderStatus
from flumine.markets.market import Market
from flumine.streams.betfairmarketstream import BetfairMarketStream
from betfairlightweight.filters import streaming_market_filter
from betfairlightweight.resources import MarketBook


class ExampleStrategy(BaseStrategy):
    def start(self, flumine) -> None:
        print("starting strategy 'ExampleStrategy'")

    def check_market_book(self, market: Market, market_book: MarketBook) -> bool:
        # process_market_book only executed if this returns True
        if market_book.status != "CLOSED":
            return True

    def process_market_book(self, market: Market, market_book: MarketBook) -> None:
        # process marketBook object
        for runner in market_book.runners:
            if runner.status == "ACTIVE" and runner.last_price_traded < 1.5:
                trade = Trade(
                    market_id=market_book.market_id,
                    selection_id=runner.selection_id,
                    handicap=runner.handicap,
                    strategy=self
                )
                order = trade.create_order(
                    side="LAY",
                    order_type=LimitOrder(price=1.01, size=2.00)
                )
                market.place_order(order)

    def process_orders(self, market: Market, orders: list) -> None:
        for order in orders:
            if order.status == OrderStatus.EXECUTABLE:
                if order.size_remaining == 2.00:
                    market.cancel_order(order, 0.02)  # reduce size to 1.98
                if order.order_type.persistence_type == "LAPSE":
                    market.update_order(order, "PERSIST")
                if order.size_remaining > 0:
                    market.replace_order(order, 1.02)  # move


# Initialize your client
trading = betfairlightweight.APIClient("username")
client = clients.BetfairClient(trading)

# Initialize the framework
framework = Flumine(client)

# Add your strategy to the framework with a stream
framework.add_strategy(
    ExampleStrategy(
        stream=BetfairMarketStream(
            market_filter=streaming_market_filter(
                event_type_ids=["7"],
                country_codes=["GB"],
                market_types=["WIN"],
            ),
        )
    )
)

# Start the trading framework
framework.run()

features

Streaming
Multiple strategies
Multiple clients
Order execution
Paper trading
Simulation
Event simulation (multi market)
Middleware and background workers to enable Scores / RaceCard / InPlayService

dependencies

flumine relies on these libraries:

betfairlightweight - Betfair API support
betdaq-retail - BETDAQ API support
betconnect - BetConnect API support
tenacity - Used for connection retrying (streaming)
python-json-logger - JSON logging
requests - HTTP support
smart-open - Efficient streaming of very large files from/to storages such as S3, including (de)compression

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flumine-3.2.2.tar.gz (3.3 MB view details)

Uploaded Sep 7, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

flumine-3.2.2-py3-none-any.whl (91.3 kB view details)

Uploaded Sep 7, 2026 Python 3

File details

Details for the file flumine-3.2.2.tar.gz.

File metadata

Download URL: flumine-3.2.2.tar.gz
Upload date: Sep 7, 2026
Size: 3.3 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.10.21

File hashes

Hashes for flumine-3.2.2.tar.gz
Algorithm	Hash digest
SHA256	`399b3c076e341bb78823a89832232f50d033c8dac26df12c8cf3edd91e6b2eca`
MD5	`ad2c9d8fc218c2b8e09533d671f2ac98`
BLAKE2b-256	`9fa156a437f1df2707de34b3e626c6e7f1b9013103ca14dcd5af0732c9d4af12`

See more details on using hashes here.

File details

Details for the file flumine-3.2.2-py3-none-any.whl.

File metadata

Download URL: flumine-3.2.2-py3-none-any.whl
Upload date: Sep 7, 2026
Size: 91.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.10.21

File hashes

Hashes for flumine-3.2.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`780462daac37b48bb6c081ac285792311f9d1cdb0a46dad77a78c92fe2c34210`
MD5	`158fe88d6dbb0adedaf59abcf391bd7e`
BLAKE2b-256	`3ea78d2a9df4942fffe3f575eccc7b51a80cb6942037497e54b172e5d7d98269`