01 — Use Case Definition
++ Detect risk-free (or near risk-free) arbitrage opportunities on Kalshi β the first + CFTC-regulated prediction market in the United States β and deliver actionable alerts in real time. + Scanning is read-only; no automated trade execution. +
+ +What is prediction market arbitrage?
++ Kalshi organizes markets in a hierarchy: Series β Event β Markets. Markets within + an event are mutually exclusive β exactly one resolves YES ($1.00). When the sum of all YES + prices drifts away from $1.00, or when logically related markets across events are inconsistently + priced, a mathematical profit opportunity exists. +
+ +Rebalancing Arbitrage
+When Ξ£(YES prices) within a mutually exclusive event β $1.00, buying all YES (if under) or + all NO (if over) locks in risk-free profit.
+Event: KXFED-25JUN (Fed June Meeting)
+Rate stays 4.375% YES: $0.45
+Rate +25bp YES: $0.32
+Rate +50bp YES: $0.12
+Rate -25bp YES: $0.08
+ββββββββββββββββββββββββββββ
+TOTAL: $0.97
+Cost to buy all YES: $0.97
+Guaranteed payout: $1.00
+Profit: $0.03 (3.1%)Combinatorial Arbitrage
+When logically dependent markets across events have inconsistent pricing β e.g., "BTC > + $100k" priced higher than "BTC > $80k" (an implication violation).
+Cross-event: Temperature thresholds
+NYC > 80Β°F on July 4 YES: $0.35
+NYC > 75Β°F on July 4 YES: $0.30
+
+Logical rule: If >80Β°F then >75Β°F
+β΄ P(80Β°F) must be β€ P(75Β°F)
+
+Violation detected β arbitrageWhy Kalshi?
+| Feature | +Kalshi | +Polymarket | +
|---|---|---|
| US Legal | +β CFTC-regulated | +β Blocks US users | +
| Currency | +Real USD | +USDC (crypto) | +
| Deposits | +Bank / debit (ACH) | +Crypto wallet | +
| KYC | +Required (SSN) | +Optional | +
| Real-time API | +REST + WebSocket | +REST + CLOB | +
02 — The OpenClaw Framework
++ OpenClaw is an open-source agent + framework that provides a persistent Gateway (daemon), multi-channel messaging + (Discord, Telegram, Slack, WhatsApp, iMessageβ¦), a skill/plugin system, cron scheduling, persistent + memory, and tool execution β all running on a dedicated machine you control. +
+ +Why an agent framework for arbitrage?
++ A simple Python script can scan for arbitrage. But a system needs: scheduled dependency + refreshes, multi-channel alerting, health monitoring, automatic restarts, persistent context, and β + crucially β the ability to ask the agent ad-hoc questions about what it's seeing. OpenClaw provides + all of that out of the box. +
+ +Gateway
+Always-on daemon on a dedicated Mac Mini. Single point through which all channels, tools,
+ sessions, and events route. Binds to localhost:18789 β never exposed to the
+ internet.
Skills
+Zip-packaged plugins with markdown instructions and scripts. The Kalshi skill contains all + scanner scripts, context, and agent instructions. Loaded from disk β fully auditable.
+Multi-Channel
+Discord channels for categorized alerts (combinatorial, rebalancing, heartbeat, errors). Also + supports Telegram, Slack, WhatsApp, iMessage β route anywhere.
+Cron Scheduling
+Built-in cron with timezone support. Runs dependency refreshes (daily 6am), market summaries + (8:30am/4pm), health checks (every 4h) β all managed through the CLI.
+Persistent Memory
+Local archive of context, preferences, session history. The agent remembers your bankroll, + risk tolerance, and market observations across sessions.
+Diagnostics
+openclaw doctor surfaces risky configurations, and
+ openclaw security audit validates your setup after every update.
+
03 — Agent Architecture
++ The system follows the Agent-Native Architecture principles. Four core tenets + drove every design decision: +
+ +Parity
+Whatever a human can do through a CLI or API, the agent can achieve through tools. The + scanner scripts are tools the agent invokes β not black boxes.
+Granularity
+Atomic primitives over monolithic workflows. Separate scripts for scanning, dependency + analysis, position sizing β the agent composes them, not us.
+Composability
+New features = new prompts. Adding "post a daily summary" required zero code changes β just a + new cron job with a natural-language instruction.
+Emergent Capability
+The agent can answer questions we didn't build features for β "which series had the most arb + opportunities this week?" β by composing existing tools.
+System Topology
+The context.md Pattern
+
+ Following the agent-architecture guide, the Kalshi skill uses a context.md file that
+ the agent reads at session start. This is the "shared state" between human and agent β bankroll,
+ risk tolerance, channel IDs, scanner status, and health history. The agent updates it; the human
+ audits it.
+
# Kalshi Context
+
+## Bankroll
+- Current: $1,000
+- Max per position: $100 (10%)
+- Kelly fraction: 0.5 (half-Kelly)
+
+## Risk Tolerance
+- Minimum profit threshold: 2%
+- Minimum liquidity: $500 volume
+
+## Discord Channels
+- Combinatorial: channel:YOUR_CHANNEL_ID
+- Rebalancing: channel:YOUR_CHANNEL_ID
+- Heartbeat: channel:YOUR_CHANNEL_ID
+- Errors: channel:YOUR_CHANNEL_ID
+
+## Preferences
+- Auto-trade: DISABLED04 — Data Pipeline
++ The data pipeline has two legs: a daily LLM-powered dependency analysis, and a 24/7 real-time + WebSocket scanner. Both are standalone Python scripts invoked as OpenClaw tools. +
+ +Pipeline Flow
+Dependency Analysis
+LLM pairs top 5 events/series, detects logical relationships. Daily via cron.
+Market Data Ingest
+REST API loads 30k-50k open markets on startup. Organizes by Series β Event.
+WebSocket Stream
+Persistent connection to Kalshi ticker channel. Real-time price updates ~100ms.
+Arbitrage Detection
+Rebalancing (Ξ£ YES β $1) + Combinatorial (implication violations). Fee-aware filtering.
+Alert Delivery
+Discord threads with descriptive names. Categorized across 4 channels.
+Dependency Generation (market_dependencies.py)
+ Real-Time Scanner (realtime_scanner.py)
+ WebSocket vs. Polling
+| Aspect | +WebSocket (Production) | +Polling (Debug/Ad-hoc) | +
|---|---|---|
| Latency | +~100ms | +Minutes | +
| Rate Limits | +None (single connection) | +20 req/sec (Basic tier) | +
| Auth Required | +No (public ticker channel) | +No (public REST) | +
| Best For | +Production monitoring | +One-shot checks, testing | +
Discord Alert Pattern
+| Channel | +Purpose | +Frequency | +
|---|---|---|
#arbitrage-combinatorial |
+ Cross-market logical pricing violations | +On detection | +
#arbitrage-rebalancing |
+ Ξ£(YES) β $1.00 within mutually exclusive events | +On detection | +
#kalshi-heartbeat |
+ Health checks + market open/close/EOD summaries | +Every 4h + scheduled | +
#kalshi-errors |
+ Scanner down, WebSocket errors, crash notifications | +On error only | +
+ Every alert creates a thread with a descriptive name (e.g., "BTC above 99k + threshold") β analysis happens in-thread, keeping channels clean. +
+05 — Security Model
++ OpenClaw is powerful β persistent memory, multi-channel control, shell access. Per Simon Willison, + it's the most likely candidate for a "Challenger disaster" in agent security. The architecture was + hardened following our OpenClaw Setup Guide (compiled from the security research + of Willison, + Cisco AI Defense, IBM Research, and Palo Alto Networks). +
+ +Willison's Lethal Trifecta
+OpenClaw hits all three risk vectors simultaneously. The goal: + break the trifecta wherever possible. +
+ +Security Architecture Decisions
+ +Dedicated Machine
+Mac Mini (~$600). Runs the Gateway and nothing else. If compromised, blast radius is + contained β your laptop, browser, passwords are untouched.
+Localhost-Only Gateway
+Gateway binds to 127.0.0.1:18789. Never 0.0.0.0. Remote access
+ exclusively through Tailscale VPN. Control UI is localhost-only.
API Key Isolation
+Dedicated Anthropic key with $50-100/mo hard cap at the provider dashboard. Separate from all + other projects. Rotated monthly.
+RSA-PSS Authentication
+Kalshi uses RSA key signing, not simple secrets. Private key stored at chmod 600
+ on the dedicated machine. Never leaves disk.
Discord DM Allowlist
+DM policy set to allowlist β only the operator's Discord user ID can issue
+ commands. Blocks prompt injection via DMs from other users.
Memory Hygiene
+Regular audits of openclaw memory list. Look for instructions, URLs, or
+ directives you didn't put there. Purge after any suspicious behavior.
Account Tiering
+| Tier | +Connect? | +Examples | +Rationale | +
|---|---|---|---|
| Tier 1 β | +Yes | +Calendar, reminders, public APIs, weather | +Low stakes, nothing irreversible | +
| Tier 2 β | +Carefully | +Email (alias only), messaging channels | +Prompt injection surface β anyone can message your agent | +
| Tier 3 β | +No | +Banking, primary Google, work accounts | +Exfiltration attacks demonstrated against more mature platforms | +
openclaw doctor +
+ openclaw security audit after every update.
+ Monthly Security Checklist
+Rotate API Keys
+Regenerate Anthropic + Kalshi API keys. Update on dedicated machine only.
+Audit Memory
+Run openclaw memory list. Remove any rogue instructions or unknown entries.
Re-check Skills
+Verify only expected skills are installed. Remove anything you didn't add.
+Run Diagnostics
+Execute openclaw doctor to surface config drift or security warnings.
Verify Control UI
+Confirm Control UI is not publicly accessible. Should only respond on localhost.
+Review Accounts
+Check connected Discord accounts and channel permissions. Remove stale entries.
+06 — Skills & Tool Design
++ Following the agent-architecture principle of granularity β atomic primitives over + monolithic workflows β each script does exactly one thing. The agent composes them. +
+ +| Script | +Purpose | +Runtime | +Auth | +Cost | +
|---|---|---|---|---|
realtime_scanner.py β‘ |
+ 24/7 WebSocket scanner β both rebalancing + combinatorial | +Daemon (always-on) | +API key (WebSocket auth) | +$0 | +
market_dependencies.py π§ |
+ LLM-based dependency detection β generates dependencies.json |
+ One-shot (daily cron) | +Anthropic API | +~$1.50-2/run | +
rebalancing_scanner.py |
+ Quick one-shot rebalancing check (REST polling) | +One-shot (debug/test) | +None (public REST) | +$0 | +
combinatorial_scanner.py |
+ One-shot cross-market logic scan (legacy) | +One-shot (debug/test) | +None (public REST) | +$0 | +
bankroll.py |
+ Kelly criterion position sizing calculator | +One-shot | +None (local calc) | +$0 | +
test_scanner.py |
+ 3-stage validation suite (synthetic + live) | +One-shot (CI/test) | +Stage 2: none | +$0 | +
Skill File Structure
+~/.openclaw-kalshi/skills/kalshi/
+βββ SKILL.md # Agent instructions (markdown)
+βββ context.md # User context (bankroll, channels, prefs)
+βββ scripts/
+ βββ realtime_scanner.py
+ βββ market_dependencies.py
+ βββ rebalancing_scanner.py
+ βββ combinatorial_scanner.py
+ βββ bankroll.py
+ βββ test_scanner.py
+ βββ requirements.txt
+ βββ dependencies.json # LLM-generated (output of market_dependencies.py)Design Principle: Tools Are Primitives
+β Wrong β Bundled Logic
+scan_analyze_and_alert(markets)
+# one tool does everything
+# can't change behavior without codeβ Right β Atomic Primitives
+realtime_scanner.py # detects
+market_dependencies.py # analyzes
+bankroll.py # sizes
+discord tool # alerts
+# agent composes; behavior = prompts07 — Operations & Reliability
++ The system is designed to self-heal. System cron restarts the scanner every 5 minutes if it dies. + OpenClaw cron runs health checks every 4 hours and posts status to Discord. +
+ +Cron Schedule
+| Job | +Schedule (CT) | +Type | +Purpose | +
|---|---|---|---|
| Scanner auto-restart | +Every 5 min | +System cron | +Checks if realtime_scanner.py is alive; restarts if not |
+
| Dependency refresh | +Daily 6:00 AM | +OpenClaw cron | +Regenerate dependencies.json via Claude (~$1.50) |
+
| Market open summary | +8:30 AM weekdays | +OpenClaw cron | +Post scanner status + overnight opportunities to heartbeat | +
| Market close summary | +4:00 PM weekdays | +OpenClaw cron | +Post today's opportunities + best edge seen | +
| EOD summary | +10:00 PM daily | +OpenClaw cron | +Full daily recap, scanner health, dependency cache age | +
| Health check | +Every 4h at :30 | +OpenClaw cron | +Verify process + log freshness; post to heartbeat, errors to errors | +
Restart After Reboot
+
+ Everything in ~/.openclaw-kalshi/ (skills, .env, config, PEM key, dependencies.json)
+ survives reboots. Only 3 processes need restart:
+
Load env vars
+source ~/.openclaw-kalshi/.env
Start Gateway
+nohup openclaw gateway run
Start Scanner
+nohup python3 realtime_scanner.py
Credential Storage Map
+| Credential | +Storage | +Method | +Used By | +
|---|---|---|---|
| Anthropic API Key | +OpenClaw config | +openclaw onboard wizard |
+ Gateway (LLM calls) | +
| Anthropic API Key | +~/.openclaw-kalshi/.env |
+ Environment variable | +Python scripts (dependencies) | +
| Discord Bot Token | +OpenClaw config | +openclaw onboard wizard |
+ Gateway (Discord channel) | +
| Kalshi API Key ID | +~/.openclaw-kalshi/.env |
+ Environment variable | +Scanner (WebSocket auth) | +
| Kalshi Private Key | +File on disk (chmod 600) |
+ RSA-PSS signing | +Scanner (request signing) | +
08 — Build Phases & Status
+ +Phase 1 β OpenClaw Infrastructure Complete
+Dedicated Mac Mini, Gateway running, Tailscale configured, openclaw doctor
+ passing.
Phase 2 β Kalshi API Integration Complete
+REST + WebSocket API access. RSA-PSS authentication. Market data ingestion verified.
+Phase 3 β Rebalancing Scanner Complete
+rebalancing_scanner.py β detects Ξ£(YES) β $1.00 within mutually exclusive
+ events.
Phase 4 β Combinatorial Scanner Complete
+combinatorial_scanner.py + market_dependencies.py β LLM-powered
+ cross-market logic analysis.
Phase 5 β Real-Time Scanner Complete
+realtime_scanner.py β unified WebSocket scanner with both detection types,
+ Discord routing, auto-restart.
Phase 6 β Paper Trading Pending +
+Validate with Kalshi demo environment. Measure detection accuracy, false positive rate, + latency.
+Phase 7 β Live Execution Pending
+Trade execution skills (limit orders, abort logic). Half-Kelly sizing with configurable + guardrails.
+Success Metrics
+09 — Applying This to Your Use Case
++ This reference architecture is designed for your engineering team to use as a template. The pattern + generalizes to any use case that follows the "always-on monitoring β intelligent analysis β + human-in-the-loop alerting" model. +
+ +The Generalizable Pattern
+Isolate
+Dedicated machine. Localhost gateway. Scoped credentials.
+Ingest
+Build atomic data-fetch scripts. REST + WebSocket. No monoliths.
+Analyze
+LLM for judgment, code for math. Separate concerns into scripts.
+Alert
+Multi-channel delivery. Categorized. Threaded. Actionable.
+Operate
+Auto-restart cron. Health checks. Memory audits. Monthly rotation.
+Example Use Cases That Fit This Pattern
+Stock Market Monitoring
+Replace Kalshi API with Alpaca. Same scanner pattern β volume breakouts, VWAP bounces, HOD on + volume. Alert to Discord channels per strategy.
+Security Event Monitoring
+Ingest SIEM logs. LLM triages alerts by severity and context. Threaded Discord alerts for + each incident. Daily summary of threat landscape.
+Competitive Intelligence
+Monitor competitor websites, patent filings, job postings. LLM identifies strategic signals. + Weekly briefings to your team's Telegram channel.
+What to Replicate
+| Component | +What We Did | +What You'd Swap | +
|---|---|---|
| Data Source | +Kalshi REST + WebSocket API | +Your domain API | +
| Analysis | +Rebalancing math + LLM dependency detection | +Your domain logic + LLM judgment | +
| Skills | +SKILL.md + Python scripts + context.md |
+ Same structure, your instructions | +
| Alert Channels | +4 Discord channels (categorized) | +Any OpenClaw-supported channel | +
| Scheduling | +5 OpenClaw cron jobs + 1 system cron | +Your schedule, same tooling | +
| Security | +Dedicated Mac Mini, localhost, Tailscale | +Don't change this part | +
SKILL.md with agent instructions, fill in context.md with your
+ parameters, and write atomic scripts for your domain. The OpenClaw framework handles the rest β
+ scheduling, alerting, memory, health checks, and multi-channel delivery.
+ References
+-
+
- π¦ OpenClaw Framework β open-source agent framework +
- 🏗️ Agent-Native Architecture — design principles for agent-first + applications +
- 🔒 OpenClaw Setup Guide β security hardening reference (Willison, Cisco, + IBM, Palo Alto Networks) +
- π Unravelling the Probabilistic Forest β arbitrage research paper ($40M + extracted) +
- π Kalshi API + Documentation +
- π§ͺ Kalshi Demo + Environment +