README

README.md

KalshiTrader

An autonomous trading research platform for Kalshi event markets, built on Elixir/Phoenix + Postgres. It ingests the full market universe in real time, detects newly listed markets as a news signal, runs a roster of statistics-driven strategies in fee-inclusive paper mode, and keeps an audited, public track record.

Everything shown anywhere in this project is simulated (paper) trading performance unless explicitly labeled live. Nothing here is investment advice. See analysis_l.md for the regulatory posture.

Architecture

flowchart TD
    %% External APIs
    subgraph External[External Data & Venues]
        direction LR
        Kalshi[Kalshi API/WS]
        Poly[Polymarket WS]
        Gemini[Gemini WS]
        Oracles[Coinbase / NOAA / ESPN]
    end

    %% Core Application
    subgraph App[KalshiTrader (Elixir/OTP)]
        direction TB
        
        %% Ingestion
        subgraph Ingestion[Ingestion Layer]
            Sync[Market Sync & Diff]
            WS[Websocket Firehose]
            DataFetch[Data Polishers]
        end
        
        %% Intelligence
        subgraph Core[Trading & Research]
            Strats[Strategy Engine]
            Arb[Multi-Venue Arb Manager]
            Exec[Execution Engine]
            Backtest[Backtester & Tuning]
        end

        Oban[Oban Background Workers]
        
        %% Interface
        subgraph Interface[Interfaces]
            LiveView[Phoenix LiveView UI]
            API[JSON Signal Feed]
            Alerts[Discord Webhooks]
        end
    end

    %% Storage
    subgraph Storage[Data Persistence]
        DB[(PostgreSQL 16)]
        Archive[(Local Warehouse)]
    end

    %% Relationships
    Kalshi --> WS & Sync
    Poly & Gemini --> WS
    Oracles --> DataFetch

    WS & Sync & DataFetch --> DB
    WS & Sync --> Strats & Arb
    
    Strats & Arb --> Exec
    Exec --> Kalshi
    Exec --> DB

    Oban <--> DB
    Oban --> Strats

    DB --> LiveView & API
    Strats & Exec --> Alerts
    DB -.->|mix kalshi.archive| Archive

What it does

  • Ingestion — full open/unopened market snapshots diffed every 2 minutes (novel-event detection separates news from ladder churn), public trade firehose, order book tracking, hourly + 15-minute candles for 18 crypto assets (Coinbase Exchange public data with Pyth fallback + circuit breaker), NOAA forecasts for weather markets, ESPN scoreboards, and a macro release calendar (FOMC/NFP/claims/CPI).
  • Multi-venue — Polymarket and Gemini Predictions stream alongside Kalshi (public websockets for both), with deterministic cross-venue market linking, a paper arbitrage executor that locks crossed books with venue-true fees, settlement ground truth from every venue, and an evidence report that issues GO/NO-GO verdicts per pair family.
  • Strategies — 39 supervised strategy processes across six cohorts (crypto intraday/daily, arbitrage, event-driven, bias harvesting, watch-only research): range statistics, nightly-refit direction models with order-flow and book features, market making, implied-vs-realized volatility, venue lead-lag following, macro post-print entries, weather, sports, and the favorite-longshot bias family. Plain-English descriptions ship in-app; per-strategy trading-hours filters are seasonality-driven and backtest-enforced.
  • Execution realism — maker-first entries with queue-position modeling, taker fallback, exact Kalshi fee formula, slippage, take-profit/stop exits, fractional-Kelly sizing, per-market/per-underlying/total risk caps, global kill switch, live-mode micro-caps and order reconciliation.
  • Evidence discipline — point-in-time backtests (no lookahead) with exit simulation, parameter sweeps, per-strategy calibration curves, weekly fill-quality reports, and an audit log of every configuration change (who, what, before → after), including automated recommendations.
  • Operations — Oban-scheduled workers for everything (sync, settlement resolution, model refits, tuning reports, morning digest, lifecycle circuit breakers, nightly backups with offsite copy, health watchdog), Discord alert channels, and a token-authenticated JSON signal feed.

Pages

Six-item nav: Tracker · Markets (+Emerging/Proposed) · Crypto · Trading (Strategies/Signals/Positions) · Venues · Portfolio.

  • / tracker with per-user watchlists (+move alerts) and a public landing
  • /strategies control panel (cohort bulk ops, allocations, live gate + pilot, audit trail) → /strategies/:name report cards with hour-of-day P&L heatmaps · /positions open risk + stress scenarios · /signals-feed
  • /venues cross-venue radar, arb ledger with depth capacity, calibration
  • /event/:ticker ladder cockpit · /search global search · /reports
  • Public: /performance (track record + Monte Carlo risk band), /report (weekly), /developers (API), /terms, /disclaimer
  • Installable PWA with push notifications (all-alerts or critical-only)

Running it

Requirements: Elixir 1.16 / OTP 26, PostgreSQL 16.

mix setup                 # deps, DB create/migrate, assets
mix phx.server            # http://localhost:4001

Optional configuration (env or config/dev.secret.exs): Kalshi API credentials (KALSHI_API_KEY, KALSHI_PRIVATE_KEY_PATH) for the authenticated websocket and live mode; DISCORD_WEBHOOK_* for alerts; SIGNALS_API_TOKEN / mix kalshi.token mint for the API feed. Public market ingestion works without any credentials.

Useful tasks:

mix kalshi.backtest momentum_fifteen --days 14
mix kalshi.sweep hourly_range_sniper --param min_edge --values 8,12,15,20
mix kalshi.event_study --days 30       # novel-market first-print edge map
mix kalshi.token mint "subscriber"     # signals feed access
mix kalshi.webhook add "name" URL      # HMAC-signed signal webhooks
mix kalshi.archive                     # cloud -> local warehouse mirror
mix kalshi.archive.verify              # alert if the warehouse lags
mix kalshi.seasonality                 # hour/day edge from the warehouse
mix kalshi.export orders out.csv       # SELECT-only CSV export

Work is tracked as GitHub issues (label roadmap) and closed with evidence comments (evidence-closed) — commit, tests, measured results.

Deployment: see DEPLOY.md (Fly.io kit included). Project history and architecture decisions: PLAN.md.

Disclaimers

Simulated performance has inherent limitations and past performance does not indicate future results. This software is provided for research purposes; trading event contracts involves risk of loss. Not affiliated with Kalshi.

Architecture →