Documentation

Full one-page reference

Overview

SimpleFunctions is prediction market data, indicators, and autonomous trading infrastructure. 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 (all 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 — all 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 thesis create 'US-Iran war will not end quickly. Oil stays above $100 through Q2 2026.'

Pass a testable claim — a statement that can be true or false at a future date. Use single quotes (not double) so $100 isn't swallowed by your shell. Takes ~60s; system builds a causal tree, scans Kalshi + Polymarket for related contracts, identifies edges, and starts 24/7 monitoring.

4. Focused context

sf thesis 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:

1. Scans news (3 queries including one adversarial — never filters out contradictory evidence)
2. Refreshes prices from Kalshi API + Polymarket CLOB
3. Enriches orderbooks (bid/ask depth for edges > 5 cents)
4. Evaluates signals against causal tree (checks kill conditions first)
5. Computes track record (hit rate: % of edges that moved toward thesis)
6. 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

54 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):

Thesis + analysis:

Knowledge + community:

Intents + Execution:

Portfolio + trading:

X / Twitter:

Flags: --json on all commands · --share on scan, query, context, edges, markets, explore

Full reference in the Agent Guide.

Agent Contract {#agent-contract}

The CLI is designed for agent consumption. Behaviors agents can rely on:

Agent Harness {#agent-harness}

Tools for testing, backtesting, and constraining agent behavior.

Event Subscription {#events}

Long-lived structured event streams for reactive agents. Replaces polling.

Event types: market (price_cross, volume_spike, spread_widen, regime_flip), thesis (confidence_drop, confidence_rise, new_signal), position (drawdown, fill, close), portfolio (drawdown, tick_complete, halt), system (runtime.started, runtime.stopped).

Cloud Runtime {#cloud-runtime}

Run your agent runtime in the cloud. Always-on, no local laptop required. BYOK: your keys, encrypted client-side.

Key encryption: Your API keys are encrypted client-side (Argon2id key derivation) before upload. SimpleFunctions never sees plaintext credentials.

REST API

No auth needed:

Auth required (Authorization: Bearer sf_live_xxx):

X / Twitter (no auth):

Auth required (Authorization: Bearer sf_live_xxx):

Full endpoint reference in the Agent Guide.

Real-Time Data API {#realtime-data-api}

Sub-second WebSocket and REST data feed at data.simplefunctions.dev/v1/ — a separate surface from the agent / public APIs above. Built for trading agents, dashboards, quants, and risk engines that need tick-level state across Kalshi and Polymarket.

REST (no auth required at the edge — rate-limited):

WebSocket (wss://data.simplefunctions.dev/v1/ws, JSON envelopes):

Heat score (0-100 per market): 0.40 × log-vol + 0.35 × spread-tightness + 0.15 × close-to-coin-flip + 0.10 × recent-volatility. Use to filter the long tail — only subscribe to markets above a heat threshold.

curl https://data.simplefunctions.dev/v1/heartbeat
curl https://data.simplefunctions.dev/v1/markets/featured?n=20

const ws = new WebSocket('wss://data.simplefunctions.dev/v1/ws')
ws.addEventListener('open', () => ws.send(JSON.stringify({
  action: 'subscribe',
  topics: ['featured', 'ticker:KXFEDDECISION-26DEC-CUT100'],
})))
ws.addEventListener('message', e => console.log(JSON.parse(e.data)))

Full marketing + integration page: Real-Time Data API. Agent-specific patterns: Agentic Usage.

Agent Skills

Cognitive guardrails for prediction market agents. Skills are prompts that make agents disciplined.

Skills are markdown files. Create your own in ~/.sf/skills/. Browse at /skills.

Agent Runtime

Multi-daemon architecture. Your agent orchestrates background daemons that monitor, reason, and execute autonomously. Smart mode (--smart) adds LLM intelligence: soft condition gating, periodic scans, wake conditions.

sf runtime start --smart --daemon   # execution daemon with LLM intelligence
sf telegram --daemon                # push notifications + mobile agent
sf agent                            # interactive agent (reads daemon alerts)

See the Agent Runtime guide for architecture, config, and cost breakdown.

Telegram Bot

sf telegram --token YOUR_BOTFATHER_TOKEN --daemon

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:

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:

1. Each evaluation can suggest new causal factors (suggestedNodes)
2. Weekly (Monday 6 UTC), the augment agent reviews suggestions
3. LLM decides which to accept (must be genuinely new, not duplicates)
4. Accepted nodes are appended (never removed — append-only tree)
5. 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 54 MCP tools, CLI commands, REST endpoints, context response shape, and integration rules. The guide page has a "Copy everything" button for pasting into agent prompts.