SimpleFunctions Developer Manual

This is the primary manual for SimpleFunctions. Use it when you need to install the CLI, build an agent loop, call an HTTP endpoint, inspect response shapes, stream real-time data, run thesis workflows, wire MCP-compatible clients, or give another agent a precise surface map. The complete documentation index is available at https://docs.simplefunctions.dev/llms.txt. Agents should fetch that index first, then open the focused pages they need instead of scraping rendered UI.

I am an agent

Start with sf describe --all --json, pull world state, inspect markets, then choose a read, monitor, thesis, or execution workflow.

I am a developer

Call REST endpoints from curl, TypeScript, Python, services, dashboards, and agents.

I am evaluating the product

Understand the world model: what it returns, why it is different from a venue API, and how agents consume it.

I am mapping a desk or pod

Start with one capital unit: watchlist, positions, risk, intents, monitoring, ledger, and attribution.

Build With SimpleFunctions

Start with the CLI. Move down the stack only when your integration needs a lower-level surface.

Priority	Surface	Start here	Use it when
1	CLI	Quickstart, Agentic CLI, CLI command reference	You are an agent, trader, researcher, cron job, CI workflow, or local operator. This is the primary product surface.
2	HTTP API	Direct API access, REST API	You need stable HTTP contracts for services, dashboards, notebooks, or custom runtimes.
3	SDK / Agent SDK	SDK, Agent SDK	You are embedding SimpleFunctions in a TypeScript app or building a Cursor-style market-intelligence agent.
4	MCP adapter	MCP server, MCP tools reference	Your client requires MCP compatibility. Prefer CLI or API when you control the runtime.

Claude Agent SDK, Codex SDK, and Cursor SDK give an agent file, shell, editor, repo, or conversation control. SimpleFunctions gives that agent a governed prediction-market runtime: world state, market inspection, contract metadata, cost and side-effect gates, trace/replay, and semi-realtime watch inputs. The quickest path is still CLI-first:

sf status --json
sf describe --all --json
sf query "Fed rate cut" --json --limit 3
sf world --delta --json --since 1h
sf inspect KXRATECUT-26DEC31 --json

What this manual covers

Area	Start here	Why it matters
CLI control plane	Agentic CLI	Local machine-readable command surface, JSON contract, traces, policy tags.
Headless agents	Headless agent	Run `sf agent --plain --once` from cron or let Claude Code/Codex drive `sf agent --headless`.
Quickstarts	CLI, API, SDK, Agent SDK	Surface-specific first runs for operators, services, and TypeScript builders.
Production CLI agents	Production CLI agent checklist	Advanced operator checklist for unattended runs, approvals, traces, budgets, and recovery.
Thesis workflows	Thesis lifecycle	Convert a testable claim into causal tree, signals, evaluations, heartbeat, and publish state.
World model	World Model	Compact event-probability context for an agent’s working memory.
Real-time data	Real-Time Data API	Snapshots, movers, orderbooks, candles, trades, and WebSocket streams.
Cookbook	SDK research loop, Agent trader loop	Tested TypeScript patterns for SDK and Agent SDK applications.
HTTP API	REST API	Stable endpoint contracts for services, notebooks, dashboards, and custom runtimes.
SDK	SDK	TypeScript client for typed API calls, strict contract inspection, preflight, typed errors, and governed Kalshi or Polymarket execution.
Agent SDK	Agent SDK	TypeScript agent package for Cursor-style runs, strict tools, watch inputs, policy-gated execution, trace, and replay.
Execution	Trade intents	Declarative order workflow with trigger state and runtime handoff.
Market making	Market making	QuoteEngine setup, paper mode, inventory skew, spread, bias, and operational gates.
Evaluation	Evaluation and replay	Trace receipts, replay, backtests, model comparisons, and promotion gates.
Portfolio agent	Portfolio Autopilot	User-scoped views, strategies, ticks, trades, risk gates, and handoff notes.
Capital units	Desk/pod pilot	Package the same read, risk, intent, ledger, and attribution loop around one agent-owned cell or desk/pod.
MCP adapter	MCP server	Final compatibility layer for Claude Code, Cursor, Cline, and MCP-compatible agents.

The contract

Human prose is optional. The structured contract is the product. Every CLI command that supports --json returns one valid JSON document on stdout. Every API page documents the shape that downstream systems should rely on. Agents should not scrape terminal text or rendered UI.

sf query "Fed rate cut" --json --limit 3
sf world --delta --json --since 1h
sf portfolio history --json --ticks 20 --trades 10 --since 2026-04-23
sf describe --all --json

Core surfaces at a glance

Surface	Start here	What it gives you
Agentic CLI	`sf describe --all --json`	Machine-readable local command surface for agents and scripts
Headless Agent	`sf agent --plain --once "..."` / `sf agent --headless`	One-shot agent runs or NDJSON tool server for external agents
Direct HTTP API	`GET /api/public/query?q=`	Stable REST calls for services, dashboards, notebooks, and custom agents
Query API	`GET /api/public/query?q=`	Event questions mapped to Kalshi, Polymarket, context, and next actions
World State API	`GET /api/agent/world`	Compact prediction-market world model for an agent context window
Market Detail API	`GET /api/public/market/{ticker}`	One market with price, liquidity, indicators, regime, and follow-up URLs
Real-Time Data API	`https://data.simplefunctions.dev/v1`	Search, snapshots, movers, candles, trades, and orderbook data for research and market making
Portfolio API	`GET /api/portfolio/state`	User-scoped state, ticks, trades, views, strategies, and portfolio memory
Contract Tools	`GET /api/contracts/tools`	Strict SDK/Agent canonical tool manifest
Tool Inventory	`GET /api/tools`	Broad hosted compatibility inventory
SDK and Agent SDK	`@spfunctions/sdk`, `@spfunctions/agent`	TypeScript wrappers over the API, strict agent contract tools, and guarded execution
MCP adapter	`sf mcp` / MCP client config	Compatibility layer when a client requires MCP; not the primary integration path

How to think about SimpleFunctions

Venue APIs expose markets. Search APIs expose documents. SimpleFunctions returns event probability state:

normalized venue objects
market-implied probabilities
source context kept separate from prose
world-state snapshots and deltas
account and portfolio memory for authenticated agents
follow-up actions that point to inspect, screen, monitor, or execution workflows

Base URLs

Surface	URL	Use
API	`https://simplefunctions.dev`	Public query, world state, market detail, portfolio, and execution endpoints
Real-time data	`https://data.simplefunctions.dev/v1`	Raw market data, search, snapshots, movers, candles, trades, and orderbooks
WebSocket	`wss://app.simplefunctions.dev/ws`	Live ticker, orderbook, trade, candle, and featured-market frames
Terminal	`https://app.simplefunctions.dev`	Browser workspace for market search, charts, contracts, and operator workflows

First calls

sf query "Fed rate cut" --json --limit 3
sf world --delta --json --since 1h
sf inspect KXRATECUT-26DEC31 --json
sf describe --all --json

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"
curl "https://simplefunctions.dev/api/agent/world"
curl "https://simplefunctions.dev/api/public/market/KXRATECUT-26DEC31"
curl "https://data.simplefunctions.dev/v1/search?q=newsom&limit=10"

const ws = new WebSocket('wss://app.simplefunctions.dev/ws')

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    topics: ['featured', 'ticker:KXPRESNOMD-28-GN']
  }))
})

Where to go next

Need	Page
Agent-readable command surface	Agentic CLI
Claude Code, Codex, cron, or CI driving `sf`	Headless agent
Unattended production CLI agents	Production CLI agent checklist
HTTP onboarding	Direct API access
HTTP endpoints and response shapes	REST API
Compact world context for agents	World Model
Raw market-data feed	Real-Time Data API
SDK and Agent recipes	Cookbook
Tested data assembly patterns	Real-time data cookbook
User-scoped portfolio state	Portfolio CLI
Execution intent workflow	Trade intents
Automated quoting	Market making
Agent QA, replay, and backtests	Evaluation and replay
Desk or pod onboarding	Desk/pod pilot

Agent handoff checklist

Before giving SimpleFunctions to an agent, give it these rules:

Use sf describe --all --json before choosing commands.
Prefer --json whenever a command supports it.
Use sf world --json once at session start.
Use sf world --delta --json --since 1h inside long-running loops.
Inspect a market before acting on a ticker.
Treat nextActions URLs as follow-up surfaces, not prose to scrape.

sf describe --all --json
sf world --json
sf query "Fed rate cut" --json --limit 3
sf inspect KXRATECUT-26DEC31 --json

Production checklist

For a service, dashboard, or agent runtime:

Step	Use
Cache discovery	Store `sf describe --all --json` for CLI work, or `GET /api/contracts/tools` for SDK/Agent canonical tools.
Start broad	Pull `GET /api/agent/world` or `sf world --json`.
Narrow context	Use query, inspect, market detail, and portfolio endpoints only when needed.
Stream raw data	Use `wss://app.simplefunctions.dev/ws` for ticker, orderbook, trade, candle, and featured frames.
Keep state compact	Use deltas instead of polling full world state repeatedly.
Run unattended agents safely	Use `--allow read,user_data,research --deny trade,runtime,fs` until a human explicitly approves writes.
Audit agent behavior	Record traces with `sf agent --record-trace` and keep stderr separate from protocol stdout.

Launch surfaces

Open the terminal

Use the browser workspace for market search, charts, contract context, and operator handoff.

Read the API overview

Use HTTP endpoints when you need stable response shapes for services, agents, and dashboards.

Call the API directly

Start with curl, TypeScript, and Python examples.

Run a headless agent

Use sf agent --plain --once or the NDJSON tool server from Claude Code, Codex, cron, or CI.

Get started

Quickstarts

SimpleFunctions Manual

I am an agent

I am a developer

I am evaluating the product

I am mapping a desk or pod

Build With SimpleFunctions

What this manual covers

The contract

Core surfaces at a glance

How to think about SimpleFunctions

Recommended reading path

Base URLs

First calls

Where to go next

Agent handoff checklist

Production checklist

Launch surfaces

Open the terminal

Read the API overview

Call the API directly

Run a headless agent

I am an agent

I am a developer

I am evaluating the product

I am mapping a desk or pod

​Build With SimpleFunctions

​What this manual covers

​The contract

​Core surfaces at a glance

​How to think about SimpleFunctions

​Recommended reading path

​Base URLs

​First calls

​Where to go next

​Agent handoff checklist

​Production checklist

​Launch surfaces

Open the terminal

Read the API overview

Call the API directly

Run a headless agent

Build With SimpleFunctions

What this manual covers

The contract

Core surfaces at a glance

How to think about SimpleFunctions

Recommended reading path

Base URLs

First calls

Where to go next

Agent handoff checklist

Production checklist

Launch surfaces