How chrislernunes/oraculus works
1. Overall shape
- This repo is a single-process paper-trading service with two major runtime parts: a Flask web server for the dashboard/API and an async arbitrage engine running in a background thread.
- The engine scans Polymarket binary markets, generates signals, sizes paper trades, and writes state for the UI to read.
2. Runtime boundary
- app.py is the web-entry boundary: it starts Flask and launches the engine thread in the same process.
- There is no separate backend service, no queue, and no database. The main integration point between the engine and the UI is a JSON file in /tmp/oraculus_state.json.
3. Engine subsystem
- engine.py is the core trading system.
- It contains the asynchronous scan loop, market-data refresh, crypto-price polling, strategy evaluation, signal deduping/ranking, Kelly sizing, and paper-account updates.
- The engine appears to own the “business logic” boundary; the web layer is deliberately thin.
4. Market data ingestion
- The engine pulls binary market metadata from Polymarket Gamma and orderbook/depth data from the Polymarket CLOB API.
- It constructs per-market MarketData objects with YES/NO bid-ask and depth, which become the input to all strategies.
- Market refresh is periodic and slower than the main scan loop, so strategies operate on cached market snapshots between refreshes.
5. External price feed
- A separate crypto feed polls CoinGecko for BTC, ETH, and SOL spot prices.
- Those prices are used only by the DEP_GRAPH strategy’s latency/move detection; this is the only non-Polymarket external signal source.
6. Strategy layer
- The engine runs three independent arbitrage strategies in parallel:
- SPREAD_FADE
- CROSS_MARKET
- DEP_GRAPH
- Each strategy scans the same market snapshot but uses different structural relationships:
- local YES/NO quote consistency,
- cross-market mutual exclusivity,
- and dependency/price-ladder plus crypto-lag signals.
- Strategies emit normalized signals with fields like strategy, outcome, price, edge, size, and reason.
7. Execution and risk sizing
- Signals are deduplicated, ranked by edge, filtered against existing positions, and only the top signals are executed each cycle.
- Position sizing is done via fractional Kelly, capped by config limits and a hard per-bet maximum.
- The execution model is explicitly paper-only via a PaperAccount; the README says there is no live wallet or real-money execution.
8. State and data flow to the UI
- After each scan cycle, the engine writes a snapshot to /tmp/oraculus_state.json.
- The dashboard reads that state through Flask’s /api/state endpoint.
- The browser polls the API every couple of seconds, so the UI is effectively a read-only observer of engine state.
9. Presentation layer
- The dashboard is a single-page HTML app, represented by index.html and templates/index.html.
- It renders NAV, scan metrics, signals, trade history, positions, market scanner data, and charts from the state payload.
- The frontend does not compute trading logic; it visualizes engine output.
10. Configuration boundary
- config.py centralizes all tunable runtime constants: balance, Kelly cap, edge thresholds, minimum depth, fee assumptions, scan interval, refresh cadence, and CoinGecko polling interval.
- This makes the system’s behavior largely driven by a single config source shared by the engine and any tests/backtests.
11. Deployment/runtime tooling
- Procfile and start.sh indicate the app is intended to run as a hosted web service, specifically called out as Render-deployable in the README.
- requirements.txt implies a Python runtime with Flask, aiohttp, and gunicorn-style deployment components.
12. Research/backtest artifacts
- oraculus_paper.pdf is a non-runtime research artifact.
- The README references backtesting and strategy tests, but those files are not present in the tree shown; the production architecture is still clear: engine + file-backed state + Flask dashboard.
13. Important architectural constraint
- The system is intentionally simple and stateless at the infrastructure level, but the trade-off is that persistence is file-based and ephemeral.
- That means the key diagram boundaries are:
- external market feeds in,
- async engine processing,
- local JSON state out,
- Flask/UI read-only on top.
Main entry points: engine.py engine.py · app.py app.py · index.html Dashboard · Procfile Procfile
Components 19
Runtime
Single-process web app and background engine
Market Data
External feeds and cached inputs
- Market cache · Cached per-market metadata, quotes, and depth used by all strategies
- Gamma API · Polymarket market metadata source
- CLOB API · Polymarket orderbook and depth source
- CoinGecko · BTC, ETH, and SOL spot prices used by one strategy
Strategy
Signal generation and ranking
- Signal ranker · Deduplicates signals, ranks by edge, and filters against positions
- Spread Fade · Checks YES/NO quote consistency inside a market
- Cross Market · Finds arbitrage across mutually exclusive markets
- Dep Graph · Uses dependency graph relationships and crypto lag signals
Execution
Paper trading and risk sizing
- PaperAccount · Virtual account that tracks positions and PnL without live trading
- Kelly sizing · Fractional Kelly position sizing with caps and bet limits
UI
Read-only dashboard and API
- Dashboard · Single-page dashboard rendering state, signals, positions, and charts
templates/index.html - /api/state · Flask endpoint exposing the latest engine snapshot
Ops
Runtime configuration and deployment
- config.py · Central tuning knobs for scan cadence, thresholds, sizing, and fees
config.py - Procfile · Process definition for hosted deployment
Procfile - start.sh · Shell launcher for the hosted runtime
start.sh - requirements.txt · Runtime dependency set for Flask, async networking, and deployment
requirements.txt
Connections 25
- app.py → engine.py: starts · Launches the async engine in a background thread
- app.py → /api/state: serves · Flask exposes the state endpoint
- /api/state → State file: reads · API returns the latest snapshot from disk
- Dashboard → /api/state: polls · Browser refreshes read-only state every few seconds
- engine.py → config.py: uses · Reads shared runtime thresholds and cadence
- engine.py → Gamma API: fetches · Loads market metadata periodically
- engine.py → CLOB API: fetches · Refreshes orderbook and depth data
- engine.py → CoinGecko: polls · Reads crypto spot prices for latency detection
- Gamma API → Market cache: feeds · Market metadata is normalized into cached snapshots
- CLOB API → Market cache: feeds · Quote and depth data populate the market cache
- CoinGecko → Dep Graph: signals · Crypto prices inform dependency/lag logic
- Market cache → Spread Fade: inputs · Strategy scans local YES/NO consistency
- Market cache → Cross Market: inputs · Strategy scans related markets for mispricing
- Market cache → Dep Graph: inputs · Strategy scans structural dependency relationships
- Spread Fade → Signal ranker: emits · Normalizes candidate arbitrage signals
- Cross Market → Signal ranker: emits · Normalizes candidate arbitrage signals
- Dep Graph → Signal ranker: emits · Normalizes candidate arbitrage signals
- Signal ranker → Kelly sizing: selects · Top-ranked signals are sized after dedupe and filters
- Kelly sizing → PaperAccount: executes · Paper-only trade updates positions and PnL
- PaperAccount → State file: persists · Engine writes the snapshot consumed by the UI
- engine.py → State file: writes · Publishes scan metrics, signals, trades, and positions
- Dashboard → State file: renders · Frontend displays the latest engine output indirectly through the API
- Procfile → app.py: starts · Deployment process launches the Flask app
- start.sh → app.py: boots · Shell startup script invokes the web process
- requirements.txt → app.py: supports · Declared dependencies enable the runtime stack