Architecture

​

System Components

​

Component Overview

genetic/
├── genome.py          # Genome definition and decoding
├── evolution.py       # Selection, crossover, mutation
├── bot.py            # Individual trading bot logic
├── engine.py         # Paper trading simulation
├── feed.py           # Centralized market data
├── runner.py         # Main evolution loop
├── monitor.py        # Logging and progress tracking
├── persistence.py    # State saving and recovery
└── config.py         # System configuration

​

Core Components

​

Genome (genome.py)

• Genome: Dataclass with 22 floating-point genes (all in [0.0, 1.0])
• decode_genome(): Converts normalized gene values to actual trading parameters

• Market Selection (5 genes)
• Entry Signals (8 genes)
• Side Selection (2 genes)
• Position Sizing (3 genes)
• Risk Management (4 genes)

​

Evolution Engine (evolution.py)

def evaluate_fitness(bot: GeneticBot) -> float:
    acct = bot.account
    if acct.n_settled < MIN_SETTLED_TRADES:
        return INACTIVE_FITNESS_PENALTY
    return acct.roi_pct

def select_parent(population: list[GeneticBot]) -> GeneticBot:
    candidates = random.sample(population, TOURNAMENT_SIZE)
    return max(candidates, key=evaluate_fitness)

def crossover(parent_a: Genome, parent_b: Genome, gen_num: int) -> Genome:
    child = Genome(generation=gen_num, parent_ids=[parent_a.id, parent_b.id])
    for gene_name in Genome.gene_names():
        if random.random() < 0.5:
            setattr(child, gene_name, getattr(parent_a, gene_name))
        else:
            setattr(child, gene_name, getattr(parent_b, gene_name))
    return child

def mutate(genome: Genome) -> Genome:
    for gene_name in Genome.gene_names():
        if random.random() < MUTATION_RATE:  # 0.15
            old_val = getattr(genome, gene_name)
            delta = random.gauss(0, MUTATION_SIGMA)  # 0.10
            new_val = max(0.0, min(1.0, old_val + delta))
            setattr(genome, gene_name, new_val)
    return genome

​

Trading Bot (bot.py)

class GeneticBot:
    def __init__(self, genome: Genome, feed: MarketDataFeed, 
                 engine: PaperTradingEngine, known_categories: list[str],
                 bankroll: float = 100.0):
        self.genome = genome
        self.params = decode_genome(genome, known_categories)
        self.bot_id = f"bot_{genome.id}"
        self.account = engine.create_account(self.bot_id, bankroll)

• price_level: Buy when ask is in specific price range
• momentum: Buy based on price direction over lookback window
• mean_reversion: Buy when price deviates from mean by z-score threshold
• value: Buy whichever side is cheapest vs 50/50 fair value
• contrarian: Bet against the crowd when market is very confident

​

Paper Trading Engine (engine.py)

@dataclass
class PaperPosition:
    id: str
    bot_id: str
    market_ticker: str
    side: str  # "yes" or "no"
    contracts: int
    entry_price: float  # Per contract, in dollars
    cost: float  # contracts * entry_price
    entry_time: datetime
    close_time: datetime | None
    
    # Filled on settlement
    settled: bool = False
    result: str = ""  # "yes" or "no" -- market outcome
    payout: float = 0.0  # contracts if won, else 0
    profit: float = 0.0  # payout - cost
    settle_time: datetime | None = None

class PaperTradingEngine:
    def try_buy(self, bot_id: str, market_ticker: str, 
                side: str, usd_amount: float) -> PaperPosition | None:
        """
        Simulate a buy order:
        - Fills at displayed ask price (yes_ask or no_ask)
        - Integer contracts only (like real Kalshi)
        - Checks available cash
        - Prevents duplicate positions in same market
        """

1. Passive checks: Every tick, check cached settlement data
2. Targeted checks: Every 10 ticks (~5 min), query API for positions that passed close time
3. Settlement wait: After trading period, wait up to 4 hours for markets to settle
4. Force close: Any remaining unsettled positions closed as losses

​

Market Data Feed (feed.py)

• Open markets closing within 24 hours
• Price history for momentum/mean-reversion signals
• Settlement data for position closing
• Event categories for market filtering

feed.get_open_markets() -> dict[str, MarketSnapshot]
feed.get_market(ticker: str) -> MarketSnapshot | None
feed.get_history(ticker: str) -> list[tuple[datetime, float]]
feed.get_settlement(ticker: str) -> str | None  # "yes", "no", or None
feed.get_categories() -> list[str]

​

Data Flow

​

Configuration

POPULATION_SIZE = 100
INITIAL_BANKROLL = 100.0  # USD per bot

# Timing
GENERATION_DURATION_SECONDS = 24 * 3600  # 24 hours
TICK_INTERVAL_SECONDS = 30

# Evolution
ELITE_COUNT = 5
TOURNAMENT_SIZE = 7
CROSSOVER_RATE = 0.7
MUTATION_RATE = 0.15
MUTATION_SIGMA = 0.10
IMMIGRATION_COUNT = 5

# Fitness
MIN_SETTLED_TRADES = 5
INACTIVE_FITNESS_PENALTY = -100.0

# Market Data
MARKET_CLOSE_WINDOW_HOURS = 24
MARKET_HISTORY_MAX_TICKS = 120

# Settlement
SETTLEMENT_WAIT_HOURS = 4
SETTLEMENT_CHECK_TICKS = 10

​

Persistence Layer

• data/evolution/gen_NNNN.json: Complete generation state
• data/evolution/checkpoint_genNNNN.json: Mid-generation snapshots
• data/evolution/hall_of_fame.json: Top 20 performers all-time
• data/evolution/latest.json: Pointer to most recent generation
• data/evolution/evolution.log: Detailed event log

save_generation_state(generation, genomes, fitness_scores, stats)
load_latest_state() -> tuple[int, list[Genome]] | None
save_hall_of_fame(generation, top_entries)
save_checkpoint(generation, bots, tick_count)

​

Performance Optimization

​

Shared Resources

• Single market data feed shared by all bots (not 100 separate feeds)
• Bulk API queries using pagination and caching
• Thread-safe read-only access to market snapshots

​

Minimal API Calls

• Background thread polls every 30 seconds
• Targeted settlement checks only for held positions
• Category refresh only every 5 minutes

​

Efficient Data Structures

• Market snapshots stored in dict[ticker, MarketSnapshot] for O(1) lookup
• Price history limited to 120 ticks (1 hour at 30s intervals)
• Settlement cache expires after 2 hours

​

Next Steps