SimpleFunctions Agent Reference

Prediction market intelligence engine. Your agent reads thesis state, injects observations, and reacts to edge changes. The backend handles news scanning, price monitoring, and evaluation continuously.

Venues: Kalshi + Polymarket. All prices in cents (0-100).

Connect

MCP (recommended for Claude Code, Cursor, Cline)

claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp

For Cursor/Cline, add to MCP config:

{"mcpServers": {"simplefunctions": {"url": "https://simplefunctions.dev/api/mcp/mcp"}}}

CLI

npm install -g @spfunctions/cli
sf setup          # interactive wizard, 2 min

Every command supports --json for machine-readable output.

REST API

Base URL: https://simplefunctions.dev. Auth: Authorization: Bearer sf_live_xxx.

Core Workflow

No thesis needed — start here

# Global market snapshot — movers, expiring, milestones, liquidity
sf context --json

# LLM-enhanced knowledge search — markets + content + synthesized answer
sf query "iran oil" --json

With a thesis — richer context

# 1. READ — thesis state (causal tree, edges, orderbook, evaluation)
sf context <id> --json

# 2. WRITE — inject your observations
sf signal <id> "Iran deploys coastal missiles near Hormuz" --type news

# 3. REACT — force deep analysis when something big happens
sf evaluate <id>

For efficient polling, use the delta endpoint instead of full context:

GET /api/thesis/:id/changes?since=2026-03-23T00:00:00Z
# Nothing changed: {"changed": false} — 50 bytes
# Changed: {"changed": true, "confidence": 0.89, "confidenceDelta": 0.02, ...}

MCP Tools (44)

Tools marked "No" work without an API key. get_context works both ways.

CLI Commands (43)

Thesis

Markets

Analysis

Knowledge

Forum + Tracking

Portfolio

Intents + Execution

Watch (smart monitoring)

Agent Runtime (smart daemons)

The agent runtime is a multi-daemon architecture. Your main agent (sf agent) orchestrates background daemons that monitor, reason, and execute autonomously.

Architecture:

• Main agent (sf agent) — interactive TUI, sets wake conditions, reads daemon alerts
• Runtime daemon (sf runtime start --smart --daemon) — evaluates intent triggers, LLM-gates soft conditions, periodic smart scans
• Telegram daemon (sf telegram --daemon) — push notifications, agent bridge for mobile
• Watch daemon (sf watch) — market monitoring across modes

Smart mode (--smart) adds an LLM intelligence layer to daemons:

• Soft conditions: Intents can have natural language conditions (e.g. "only if oil above $95"). When a hard trigger fires, the runtime asks a cheap LLM whether the soft condition is met before executing.
• Periodic scan: Every ~5 minutes, the runtime summarizes all active intents + market state and sends observations to the agent via the message bus.
• Wake conditions: The agent can set rules for when to be alerted — price thresholds, time triggers, or natural language conditions evaluated by LLM.

Communication: File-based message bus for IPC. Daemons write observations; the agent reads them. The agent writes commands; daemons read them. Agent presence detected via heartbeat file.

Config (~/.sf/config.json):

{
  "smartDaemons": true,
  "smartModel": "your-preferred-model",
  "smartScanInterval": 10,
  "smartBudgetUsd": "your_budget"
}

Trading (requires sf setup --enable-trading)

Query & X

Other

Global Flags

REST API Endpoints

All require Authorization: Bearer sf_live_xxx unless noted.

Thesis

Feed & Prompt

Intents & Execution

Public (no auth)

Context Response Shape

GET /api/thesis/:id/context returns:

{
  "thesisId": "f582bf76-...",
  "thesis": "Trump cannot exit the Iran war gracefully...",
  "status": "active",
  "confidence": 0.82,
  "causalTree": {
    "rootClaim": "...",
    "nodes": [
      {"id": "n1", "label": "...", "probability": 0.85, "importance": 0.3, "depth": 0, "childCount": 3}
    ]
  },
  "edges": [
    {
      "marketId": "KXRECSSNBER-26",
      "market": "Will there be a recession in 2026?",
      "venue": "kalshi",
      "direction": "yes",
      "marketPrice": 34,
      "thesisPrice": 55,
      "edge": 21,
      "executableEdge": 20,
      "orderbook": {"bidPrice": 33, "askPrice": 35, "spread": 2, "bidDepth": 814, "askDepth": 500, "liquidityScore": "high"}
    }
  ],
  "lastEvaluation": {
    "summary": "...",
    "confidenceDelta": 0.10,
    "updatedNodes": [{"nodeId": "n3", "previousProbability": 0.6, "newProbability": 0.75, "reason": "..."}]
  },
  "suggestedTreeExtensions": [
    {"label": "...", "description": "...", "parentNodeId": "n2", "estimatedProbability": 0.7}
  ],
  "trackRecord": {
    "hitRate": 67,
    "edgesTracked": 49,
    "movedToward": 33,
    "movedAway": 16,
    "avgMovement": 3,
    "bestEdge": {"market": "...", "delta": 21},
    "worstEdge": {"market": "...", "delta": -12}
  }
}

What The Backend Does Automatically

The heartbeat engine runs every 15 minutes for each active thesis. Your agent does NOT need to do any of this:

1. News scan — 3 targeted queries (including one adversarial/contrarian). Filters with cheap LLM. Never excludes contradictory news.
2. Price rescan — Live prices from Kalshi API + Polymarket CLOB. Injects changes >= 3 cents.
3. Orderbook enrichment — Bid/ask/depth for edges with |edge| > 5 cents.
4. Evaluation — LLM evaluates signals against causal tree. Checks kill conditions first. Updates node probabilities and confidence.
5. Track record — Computes batting average (edges that moved toward the thesis) and injects into next evaluation as feedback loop. 5b. Evolution classification (gitMode) — The LLM classifies each cycle as stable, refinement, or discontinuous. Discontinuous cycles auto-fork into a new child thesis with the same market coverage; parent enters dormant.
6. Edge discovery — Daily (6 UTC): scans for new markets matching thesis.
7. Tree augmentation — Weekly (Monday 6 UTC): reviews suggested nodes, merges accepted ones (append-only).
8. Settlement sync — Checks settled contracts, records realized returns.
9. Strategy review — Reviews strategies against updated edges.

Edge diagnosis types

Each edge is classified as: consensus_gap (market/thesis disagree), attention_gap (market hasn't reacted), timing_gap (short vs long term), or risk_premium (fear/greed premium).

Kill conditions

Before every evaluation: "Does any event fundamentally break a core assumption?" If yes, flags prominently.

Rules for Agents

1. Don't poll prices — the heartbeat does it every 15 min
2. Don't search news — the heartbeat does it with adversarial queries
3. Do inject observations immediately — inject_signal with type user_note or news
4. Only call evaluate for breaking events — routine evaluation is automatic
5. Use what_if before trades — zero LLM cost scenario analysis
6. Call get_positions before discussing trades — positions are local (Kalshi private key), backend can't see them
7. Use /changes for polling — 100x smaller than full context
8. Use short thesis IDs — first 8 chars work everywhere (e.g. f582bf76)

Writing good theses

• Be specific and directional: "Oil stays above $100 for 6 months" not "Oil prices"
• Include timeframe: helps match contracts
• One thesis = one view: don't mix unrelated predictions

Signal types

Interactive Agent

sf agent [id] launches a natural language session with 40+ tools. Supports TUI mode (default) and plain mode (--plain for pipes).

Slash commands: /tree, /edges, /pos, /eval, /buy TICKER QTY PRICE, /sell, /cancel, /switch <id>, /compact, /model <name>, /exit.

Sessions persist at ~/.sf/sessions/. Use --new for fresh session.

Telegram Bot

sf telegram --token TOKEN — runs locally, credentials stay on your machine.

Commands: /context, /positions, /edges, /balance, /orders, /eval, /list, /switch.

Natural language works too — same tools as sf agent. Auto-pushes confidence alerts every 60s.

Webhook

Configure when creating thesis: {"rawThesis": "...", "webhookUrl": "https://..."}

POSTs on confidence changes >= 5% and non-hold position recommendations.