📈 KOS: Algorithmic Arbitrage & State Tracking Engine

KOS is a production-grade Python daemon engineered to ingest real-time market data, calculate optimal arbitrage/matched-betting pairs, and manage a complex multi-tenant state machine.

Built entirely on first-principles engineering, it strips away fragile browser automation in favor of a robust, API-driven signal engine and a strict Telegram-operated state tracker.

🧠 System Architecture

KOS operates as a headless daemon (kos.py) overseeing several asynchronous supervised tasks. It bridges the gap between raw data ingestion and manual commercial execution by handling all the complex math, caching, and state transitions.

1. High-Velocity Data Ingestion (matcher.py)

• Parallel Fetching: Utilizes asyncio.gather to concurrently fetch live odds across 66 dynamic sport keys via the Odds API.
• Fuzzy Reconciliation: Integrates RapidFuzz to bridge naming disparities between global bookmakers and the Betfair Exchange.
• Aggressive Caching: Employs a multi-layered caching architecture (Betfair price cache with 2-min TTL, RapidFuzz match cache) to reduce API payload sizes and cut exchange calls by ~80%.

2. Algorithmic Signal Engine (signal_engine.py)

Calculates mathematical viability for arbitrage pairs in real-time, completely decoupled from the API fetching layer to ensure zero-latency signal generation.

• Qualifier Sort Algorithm: Ranks market opportunities using a custom weighting formula: Score = (Free Bet Value / Max Loss) * (1 / Minutes to Kickoff) * Retention Rate * Liquidity Floor
• Inversion Guards: Programmatic rejection of pairs where lay odds do not align with back odds (e.g., rejecting pairs where lay_odds < back_odds * 0.95).

3. State Machine & Event Tracking (execution.py & schema.py)

• Strict State Transitions: Tracks the lifecycle of capital through 6 distinct phases (e.g., DEPOSIT_SENT -> QUALIFYING_PLACED -> FREE_BET_PENDING).
• Multi-Tenant SQLite: Uses WAL (Write-Ahead Logging) mode and specific database indexing (idx_offers_state, idx_offers_user_id) to ensure thread-safe state management across multiple concurrent participants.
• Telegram Command Interface: Built with aiogram 3.x to allow operators to trigger state transitions and request real-time algorithmic snapshots (e.g., /qualifier_coral, /snr_laid).

🛠️ Tech Stack

• Core: Python 3, asyncio
• Data & Storage: SQLite (WAL mode), JSON state heartbeats
• External APIs: The Odds API, Betfair Exchange API (with strict liability floating)
• Reconciliation: RapidFuzz (String matching)
• Interface: Telegram Bot API (aiogram)
• Network: Decodo Residential Proxies (Session-sticky load balancing)

📈 Recent Performance Optimizations

• Refactored data fetching to run exclusively in memory via snapshot caches, allowing the signal engine to serve requests with zero additional API calls.
• Implemented sport-aware liquidity floors (e.g., EPL £50, NBA £30) and draw-exclusion logic for two-outcome US sports.
• Reduced system jitter from 90s to 5-15s via parallel asyncio gathering.