SimpleFunctions Institutional Alpha Demo

Open-source reference implementation for institutions evaluating agentic alpha research, realtime prediction-market data, and binary-market market making on SimpleFunctions.

This repository is paper-only by design. It shows the architecture, data contracts, risk checks, replay harness, and quote math that a serious desk would expect before any private execution integration is added.

Why This Exists

Prediction-market systems often collapse three different problems into one opaque bot:

1. Research: what changed in the world, and what probability should we assign?
2. Alpha mining: what does the live orderbook, momentum, volatility, and cross-venue structure imply?
3. Execution: what should we quote, cancel, hedge, and risk-limit?

This repo keeps those layers separate. LLM agents produce constrained research signals. Deterministic quant code mines microstructure signals. A risk router decides whether paper quote intents are allowed. A replay/TCA harness measures markout and adverse selection.

Included Systems

System	File	Purpose
SimpleFunctions data client	src/sf_institutional_alpha/data.py	REST access to orderbooks, candles, screeners, cross-venue pairs, and market inspection.
Fundamental agent loop	src/sf_institutional_alpha/fundamental_agent.py	Converts market context into a guarded fair-value probability using Claude -p, Codex exec, or offline fallback.
Quant alpha miner	src/sf_institutional_alpha/alpha_miner.py	Computes microprice, imbalance, momentum, volatility, cross-venue gap, and confidence.
Binary market maker	src/sf_institutional_alpha/market_maker.py	Emits inventory-aware YES and NO bid intents for binary CLOBs.
Risk router	src/sf_institutional_alpha/risk.py	Applies kill switch, staleness, spread, depth, confidence, order-size, gross, and net exposure gates.
Replay harness	src/sf_institutional_alpha/replay.py	Replays recorded orderbook frames and simulates conservative passive fills.
TCA metrics	src/sf_institutional_alpha/tca.py	Measures markout PnL, notional, average markout, and win rate.
Paper broker	src/sf_institutional_alpha/paper_broker.py	Minimal fill simulator for demos and tests.

Data Surface

The demo uses SimpleFunctions public data:

• REST: https://data.simplefunctions.dev/v1
• WebSocket: wss://app.simplefunctions.dev/ws
• Analytics: https://simplefunctions.dev/api/public/*
• Agent inspection: https://simplefunctions.dev/api/agent/inspect/:ticker

Common endpoints:

• /v1/markets/featured
• /v1/orderbook/{ticker}
• /v1/candles/{ticker}
• /v1/trades/{ticker}
• /api/public/screen
• /api/public/cross-venue/pairs
• /api/agent/inspect/{ticker}

Architecture

                SimpleFunctions REST / WS
                          |
                          v
                    Data client
                          |
        +-----------------+------------------+
        |                                    |
        v                                    v
 Fundamental context                 Orderbook + candles
        |                                    |
        v                                    v
 Claude -p / Codex exec              QuantAlphaMiner
        |                                    |
        +-----------------+------------------+
                          |
                          v
                    AlphaSignal
                          |
                          v
                  BinaryMarketMaker
                          |
                          v
                     RiskRouter
                          |
              +-----------+-----------+
              |                       |
              v                       v
       paper quote intents       replay + TCA

Binary Market Mechanics

The market maker does not treat prediction markets like equities. In binary markets, a NO bid is the venue-native equivalent of selling YES:

YES ask = 1 - NO bid

The engine therefore emits:

• buy_yes at a YES bid price.
• buy_no at a NO bid price, representing the YES ask side.

Inventory skew reduces the side that increases existing exposure and increases the side that offsets exposure. Dust orderbook levels are filtered before spread, microprice, and quote calculations.

Quick Start

git clone https://github.com/spfunctions/sf-institutional-alpha-demo.git
cd sf-institutional-alpha-demo
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Run offline samples:

python -m sf_institutional_alpha.cli quant --sample
python -m sf_institutional_alpha.cli market-make --sample
python -m sf_institutional_alpha.cli replay --trace examples/replay_trace.jsonl
python -m sf_institutional_alpha.cli fundamental --sample --provider none

Run against live SimpleFunctions public data:

python -m sf_institutional_alpha.cli discover --sort volume --limit 10 --vol-min 5000
python -m sf_institutional_alpha.cli quant --ticker KXNEXTAG-29-TBLA
python -m sf_institutional_alpha.cli market-make --ticker KXNEXTAG-29-TBLA

Agentic Fundamental Loop

Claude Code print mode:

bash scripts/run_fundamental_claude.sh KXNEXTAG-29-TBLA "Attorney General"

Codex non-interactive mode:

bash scripts/run_fundamental_codex.sh KXNEXTAG-29-TBLA "Attorney General"

Both paths request constrained JSON and then pass the output through deterministic clipping and fallback logic. The model cannot place orders.

Quant And Market-Making Loop

Generate a paper quote set from live orderbook and candle data:

python -m sf_institutional_alpha.cli market-make \
  --ticker KXNEXTAG-29-TBLA \
  --timeframe 1m \
  --limit 120

The output includes:

• signal: fair value, confidence, volatility, and features.
• quotes: YES/NO bid intents and quote diagnostics.
• risk: approved intents, suppressed sides, and risk flags.

Enable a kill switch:

python -m sf_institutional_alpha.cli market-make --sample --kill-switch

Replay And TCA

Run the included recorded trace:

python -m sf_institutional_alpha.cli replay --trace examples/replay_trace.jsonl

The replay engine uses conservative passive-fill assumptions:

• YES bid fills if the next frame's best ask is at or below the bid.
• NO bid fills if the next frame's best YES bid is at or above 1 - no_bid.
• Markout is measured against a future midpoint.

The TCA summary reports fill count, notional, markout PnL, average markout, and win rate. It is a debugging harness, not a profitability claim.

Cron

Edit config/cron.example, set REPO, then install it with your preferred cron workflow.

0 * * * * cd "$REPO" && OUT_DIR="$REPO/runs/fundamental" bash scripts/run_fundamental_claude.sh KXNEXTAG-29-TBLA "Attorney General" >> "$REPO/logs/fundamental.log" 2>&1
*/5 * * * * cd "$REPO" && OUT_DIR="$REPO/runs/market-making" bash scripts/run_quant_market_maker.sh KXNEXTAG-29-TBLA >> "$REPO/logs/market-making.log" 2>&1
15 * * * * cd "$REPO" && OUT_DIR="$REPO/runs/replay" bash scripts/run_replay.sh examples/replay_trace.jsonl >> "$REPO/logs/replay.log" 2>&1

Reports

• docs/RESEARCH_REPORT.md: external research, SimpleFunctions live probes, implementation decisions, and future research.
• docs/SYSTEM_DESIGN.md: loop architecture and quote math.
• docs/BACKTESTING_AND_TCA.md: replay input, fill model, and TCA semantics.
• docs/SAFETY_AND_RISK.md: explicit non-goals and private-production requirements.
• docs/SOURCES.md: external and local source material.

Tests

python -m unittest discover -s tests -v

What This Is Not

• Not a live trading bot.
• Not a promise of alpha.
• Not an execution adapter.
• Not a credential manager.
• Not a substitute for risk, compliance, or venue-specific controls.
• Not an endorsement that an LLM thesis is sufficient to trade.

Production Extensions

Institutional users typically add these privately:

• Venue execution adapters with idempotency keys.
• Recorded orderbook/trade lake.
• Queue-position and cancel-latency models.
• Fee/rebate and adverse-selection TCA.
• Event-family, venue, account, and strategy exposure caps.
• Cross-venue hedging after execution coverage is unified.
• Resolution-label evaluation for Brier score and fair-value calibration.
• Full audit logging for every model input, quote, cancel, fill, and override.

Use this repo as the transparent public implementation exhibit. Keep account credentials, execution policy, and production risk controls private.