Documentation
SimpleFunctions is context flow infrastructure for prediction markets. Structured, decision-ready data from Kalshi, Polymarket, X/Twitter, and traditional markets — monitored 24/7. CLI, MCP server, REST API, and interactive agent with cognitive guardrails.
Quick Start
0. No install needed — try it now
curl https://simplefunctions.dev/api # live data in your terminal
curl https://simplefunctions.dev/api/changes # recent market changes
curl https://simplefunctions.dev/api/tools # full capability manifest
1. Install the CLI
npm install -g @spfunctions/cli
sf scan "gold" # search Kalshi + Polymarket (no auth)
sf query "iran oil" # LLM-enhanced search — markets + X + answer
sf watch "gold" # server-side change detection feed
sf agent # interactive agent (25 tools + skills)
All commands work without an API key. Explorer mode gives you full market access.
2. Explore — ask questions (no thesis needed)
sf agent # opens in explorer mode — 25 tools, no setup
Ask anything: "what's happening with Iran?", "show me gold contracts", "any new markets today?". The agent has full access to scan, query, watch, and explore — no thesis required. When you form a view, say it: "I think oil stays above $100" — the agent creates a thesis automatically.
3. Create a thesis (optional — makes context richer)
sf setup # API key + optional Kalshi/Polymarket credentials (2 min)
sf create "US-Iran war will not end quickly. Oil stays above $100."
This takes ~60 seconds. The system decomposes your thesis into a causal tree, scans Kalshi + Polymarket for related contracts, identifies edges, and starts 24/7 monitoring.
4. Focused context
sf context <id> # thesis-specific: causal tree, edges, evaluation, track record
sf edges # top mispriced contracts across all theses
sf dashboard # interactive Bloomberg-style terminal
That's it. The system runs 24/7. See the Agent Guide for full integration reference.
How It Works
Thesis → Causal Tree
Your plain-text thesis is decomposed into a tree of verifiable assumptions. Each node has a probability (0-1) and importance weight. The overall confidence is the weighted product.
Thesis: "Oil stays above $100 for 6 months"
├── n1: OPEC maintains production cuts (0.70, weight 0.30)
│ ├── n1.1: Saudi compliance remains high (0.80)
│ └── n1.2: Russia doesn't break quota (0.60)
├── n2: Demand stays strong (0.65, weight 0.25)
├── n3: Geopolitical risk premium persists (0.75, weight 0.25)
└── n4: No US SPR release (0.80, weight 0.20)
Confidence: 72%
Edge Detection
The system maps causal nodes to prediction market contracts and compares:
- Market price: what Kalshi/Polymarket traders think (e.g. 34 cents)
- Thesis price: what your causal model implies (e.g. 55 cents)
- Edge: the difference (21 cents)
- Executable edge: edge minus half the spread (real edge after crossing)
24/7 Monitoring
Every 15 minutes, the heartbeat engine:
- Scans news (3 queries including one adversarial — never filters out contradictory evidence)
- Refreshes prices from Kalshi API + Polymarket CLOB
- Enriches orderbooks (bid/ask depth for edges > 5 cents)
- Evaluates signals against causal tree (checks kill conditions first)
- Computes track record (hit rate: % of edges that moved toward thesis)
- Discovers new edges (daily) and augments the causal tree with new nodes (weekly)
Integration Options
MCP Server
One-line setup for Claude Code, Cursor, Cline, or Roo Code:
claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp
25+ tools available. Public tools work without auth. See the Agent Guide for the full list.
CLI
Every command supports --json. Key commands support --share for shareable URLs.
Explore (no auth):
| Command | What it does |
|---|---|
sf scan "gold" | Search Kalshi + Polymarket |
sf query "iran oil" | LLM-enhanced search (markets + X + answer) |
sf watch "gold" | Server-side change detection feed |
sf agent | Interactive agent (25 tools + skills, explorer mode) |
sf context | Global market snapshot |
sf markets | Traditional markets (SPY, VIX, GLD, TLT, USO) |
sf explore | Browse public theses |
sf dashboard | Interactive Bloomberg-style terminal |
Thesis + analysis:
| Command | What it does |
|---|---|
sf create "thesis" | Create thesis with causal tree + edges |
sf context <id> | Thesis-specific snapshot |
sf edges | Top mispriced contracts across all theses |
sf whatif <id> --set "n1=0.1" | Scenario analysis (zero LLM cost) |
sf signal <id> "text" | Inject observation |
sf evaluate <id> | Force deep evaluation |
sf feed | Evaluation history |
Portfolio + trading:
| Command | What it does |
|---|---|
sf positions | Kalshi + Polymarket positions with P&L |
sf balance | Account balance |
sf orders | Current resting orders |
sf fills | Recent trade fills |
sf settlements | Settled contracts with P&L |
sf performance | P&L over time with sparklines |
sf buy <ticker> <qty> --price <cents> | Buy contracts |
sf sell <ticker> <qty> --price <cents> | Sell contracts |
sf cancel [orderId] | Cancel orders (--all for all) |
X / Twitter:
| Command | What it does |
|---|---|
sf x "iran oil" | Search X discussions — posts, sentiment, themes |
sf x-volume "tariffs" | Discussion volume trend with histogram |
sf x-news "tariffs" | X news stories with ticker mentions |
sf x-account @federalreserve | Recent posts from a specific account |
Flags: --json on all commands · --share on scan, query, context, edges, markets, explore
Full reference in the Agent Guide.
REST API
No auth needed:
| Endpoint | What it does |
|---|---|
GET /api/public/context | Global market snapshot (edges, signals, highlights, traditional markets) |
GET /api/public/context?compact=true | Compact: edges + highlights + traditional only (7K vs 44K) |
GET /api/public/context?q=iran | Filter by keyword (1.7K for topic-specific data) |
GET /api/public/query?q=... | LLM-enhanced search (Kalshi + Polymarket + X + traditional) |
GET /api/public/scan?q=... | Keyword search across Kalshi + Polymarket |
GET /api/changes?since=&q=&type= | Server-side market change detection (every 15 min) |
GET /api/tools | Full capability manifest for agent discovery |
GET /api/skills | Agent cognitive guardrails and workflows |
GET /api/public/markets | Traditional market snapshot (SPY, VIX, GLD, TLT, USO) |
GET /api/public/theses | List public theses |
GET /api/public/thesis/:slug | Public thesis detail with causal tree + edges |
X / Twitter (no auth):
| Endpoint | What it does |
|---|---|
GET /api/x/search?q=... | Search X discussions — posts, sentiment, themes |
GET /api/x/volume?q=... | Discussion volume trend — timeseries, velocity |
GET /api/x/news?q=... | X news stories — headlines, summaries |
GET /api/x/account?username=... | Recent posts from a specific account |
Auth required (Authorization: Bearer sf_live_xxx):
| Endpoint | What it does |
|---|---|
POST /api/thesis/create[?sync=true] | Create thesis (sync waits for formation) |
GET /api/thesis/:id/context | Thesis-specific snapshot |
GET /api/thesis/:id/changes?since=ISO | Lightweight delta check (~50 bytes) |
POST /api/thesis/:id/signal | Inject signal |
POST /api/thesis/:id/evaluate | Force evaluation (up to 2 min) |
POST /api/thesis/:id/augment | Tree augmentation (?dryRun=true to preview) |
POST /api/thesis/:id/strategies | Create trading strategy |
GET /api/thesis/:id/strategies | List strategies |
GET /api/feed?hours=24 | Evaluation history |
Full endpoint reference in the Agent Guide.
Agent Skills
Cognitive guardrails for prediction market agents. Skills are prompts that make agents disciplined.
| Skill | Trigger | What it does |
|---|---|---|
| Discipline | /discipline | Full position review: entry hypothesis, falsification, from-zero test |
| Pre-check | /precheck | Pre-trade adversarial check — argue against the trade first |
| Morning | /morning | Structured daily briefing: kill conditions, positions, action items |
Skills are markdown files. Create your own in ~/.sf/skills/. Browse at /skills.
Telegram Bot
sf telegram --token YOUR_BOTFATHER_TOKEN
Runs locally. Slash commands + natural language. Auto-pushes confidence alerts.
Webhook
Add webhookUrl when creating a thesis. The engine POSTs on confidence changes >= 5%.
Authentication
Get an API key from the Dashboard.
curl -H "Authorization: Bearer sf_live_xxx" https://simplefunctions.dev/api/thesis
For CLI: sf setup stores the key in ~/.sf/config.json. Config priority: env vars > config file > defaults.
Key Concepts
Signals
Events that feed into evaluations. Five types:
| Type | Source | Description |
|---|---|---|
news | Heartbeat or manual | News articles, data releases |
price_move | Heartbeat | Market price change >= 3 cents |
user_note | Manual | Your analysis or observations |
external | Manual | Signals from other systems |
upcoming_event | Heartbeat | Kalshi milestone matching edges |
Edge Types
The system classifies each edge by WHY the mispricing exists:
- consensus_gap — market and thesis disagree on fundamental probability
- attention_gap — market hasn't reacted to recent information yet
- timing_gap — market prices short-term risk, thesis prices long-term outcome
- risk_premium — market embeds fear/greed premium that thesis doesn't
Track Record
Feedback loop that computes how well past edges predicted market movement:
- Hit rate: % of edges where market moved toward the thesis-implied price
- Average movement: mean price change in cents since edge detection
- Track record is injected into evaluation prompts so the system learns from its accuracy
Tree Augmentation
The causal tree evolves over time:
- Each evaluation can suggest new causal factors (
suggestedNodes) - Weekly (Monday 6 UTC), the augment agent reviews suggestions
- LLM decides which to accept (must be genuinely new, not duplicates)
- Accepted nodes are appended (never removed — append-only tree)
- Importance weights are rebalanced among siblings
Kill Conditions
Before every evaluation, the system asks: "Does any event fundamentally break a core assumption of this thesis?" If yes, it flags the threat prominently before any other analysis.
Pricing
Free during beta. Pay by token after 15M tokens consumed.
Full Reference
See the Agent Guide for the complete machine-readable reference — all 25 MCP tools, 42 CLI commands, REST endpoints, context response shape, and integration rules. The guide page has a "Copy everything" button for pasting into agent prompts.