> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# SimpleFunctions Manual
> The canonical manual for SimpleFunctions — CLI, agents, HTTP APIs, real-time data, world model, workflows, and MCP adapter.
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](https://docs.simplefunctions.dev/llms.txt). Agents should fetch that index first, then open the focused pages they need instead of scraping rendered UI.
Start with `sf describe --all --json`, pull world state, inspect markets, then choose a read, monitor, thesis, or execution workflow.
Call REST endpoints from curl, TypeScript, Python, services, dashboards, and agents.
Understand the world model: what it returns, why it is different from a venue API, and how agents consume it.
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](/quickstart), [Agentic CLI](/cli/agentic-cli), [CLI command reference](/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](/build/direct-api-access), [REST API](/api-reference/overview) | You need stable HTTP contracts for services, dashboards, notebooks, or custom runtimes. |
| 3 | SDK / Agent SDK | [SDK](/sdk), [Agent SDK](/agent-sdk) | You are embedding SimpleFunctions in a TypeScript app or building a Cursor-style market-intelligence agent. |
| 4 | MCP adapter | [MCP server](/cli/mcp-server), [MCP tools reference](/reference/mcp-tools) | 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:
```bash theme={null}
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](/cli/agentic-cli) | Local machine-readable command surface, JSON contract, traces, policy tags. |
| Headless agents | [Headless agent](/build/headless-agent) | Run `sf agent --plain --once` from cron or let Claude Code/Codex drive `sf agent --headless`. |
| Quickstarts | [CLI](/start/cli-quickstart), [API](/start/api-quickstart), [SDK](/start/sdk-quickstart), [Agent SDK](/start/agent-sdk-quickstart) | Surface-specific first runs for operators, services, and TypeScript builders. |
| Production CLI agents | [Production CLI agent checklist](/build/production-agent-runbook) | Advanced operator checklist for unattended runs, approvals, traces, budgets, and recovery. |
| Thesis workflows | [Thesis lifecycle](/build/thesis-lifecycle) | Convert a testable claim into causal tree, signals, evaluations, heartbeat, and publish state. |
| World model | [World Model](/guides/world-model) | Compact event-probability context for an agent's working memory. |
| Real-time data | [Real-Time Data API](/reference/realtime-data) | Snapshots, movers, orderbooks, candles, trades, and WebSocket streams. |
| Cookbook | [SDK research loop](/cookbook/sdk-market-research-loop), [Agent trader loop](/cookbook/agent-trader-loop) | Tested TypeScript patterns for SDK and Agent SDK applications. |
| HTTP API | [REST API](/api-reference/overview) | Stable endpoint contracts for services, notebooks, dashboards, and custom runtimes. |
| SDK | [SDK](/sdk) | TypeScript client for typed API calls, strict contract inspection, preflight, typed errors, and governed Kalshi or Polymarket execution. |
| Agent SDK | [Agent SDK](/agent-sdk) | TypeScript agent package for Cursor-style runs, strict tools, watch inputs, policy-gated execution, trace, and replay. |
| Execution | [Trade intents](/build/trade-intents) | Declarative order workflow with trigger state and runtime handoff. |
| Market making | [Market making](/build/market-making) | QuoteEngine setup, paper mode, inventory skew, spread, bias, and operational gates. |
| Evaluation | [Evaluation and replay](/build/evaluation-replay) | Trace receipts, replay, backtests, model comparisons, and promotion gates. |
| Portfolio agent | [Portfolio Autopilot](/guides/portfolio-autopilot) | User-scoped views, strategies, ticks, trades, risk gates, and handoff notes. |
| Capital units | [Desk/pod pilot](/build/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](/cli/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.
```bash theme={null}
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
## Recommended reading path
Read the [Quickstart](/quickstart), run one public query, and inspect one market.
Read [World Model](/guides/world-model) and decide when your agent should call full state, delta, query, and inspect.
Use the [CLI](/cli/agentic-cli) for local agent workflows or [Direct API access](/build/direct-api-access) for HTTP integration.
Use [Headless agent](/build/headless-agent) for external coding agents, [Thesis lifecycle](/build/thesis-lifecycle) for research loops, [Trade intents](/build/trade-intents) for execution, and [Market making](/build/market-making) for QuoteEngine. Use the [Production CLI agent checklist](/build/production-agent-runbook) only when promoting unattended jobs.
Use [Desk/pod pilot](/build/desk-pod-pilot) when the integration target is a desk, pod, agent-owned capital cell, or internal FDE build.
## 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
```bash CLI theme={null}
sf query "Fed rate cut" --json --limit 3
sf world --delta --json --since 1h
sf inspect KXRATECUT-26DEC31 --json
sf describe --all --json
```
```bash REST theme={null}
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"
```
```js WebSocket theme={null}
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](/cli/agentic-cli) |
| Claude Code, Codex, cron, or CI driving `sf` | [Headless agent](/build/headless-agent) |
| Unattended production CLI agents | [Production CLI agent checklist](/build/production-agent-runbook) |
| HTTP onboarding | [Direct API access](/build/direct-api-access) |
| HTTP endpoints and response shapes | [REST API](/api-reference/overview) |
| Compact world context for agents | [World Model](/guides/world-model) |
| Raw market-data feed | [Real-Time Data API](/reference/realtime-data) |
| SDK and Agent recipes | [Cookbook](/cookbook/sdk-market-research-loop) |
| Tested data assembly patterns | [Real-time data cookbook](/build/realtime-data-cookbook) |
| User-scoped portfolio state | [Portfolio CLI](/cli/portfolio) |
| Execution intent workflow | [Trade intents](/build/trade-intents) |
| Automated quoting | [Market making](/build/market-making) |
| Agent QA, replay, and backtests | [Evaluation and replay](/build/evaluation-replay) |
| Desk or pod onboarding | [Desk/pod pilot](/build/desk-pod-pilot) |
## Agent handoff checklist
Before giving SimpleFunctions to an agent, give it these rules:
1. Use `sf describe --all --json` before choosing commands.
2. Prefer `--json` whenever a command supports it.
3. Use `sf world --json` once at session start.
4. Use `sf world --delta --json --since 1h` inside long-running loops.
5. Inspect a market before acting on a ticker.
6. Treat `nextActions` URLs as follow-up surfaces, not prose to scrape.
```bash theme={null}
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
Use the browser workspace for market search, charts, contract context, and operator handoff.
Use HTTP endpoints when you need stable response shapes for services, agents, and dashboards.
Start with curl, TypeScript, and Python examples.
Use `sf agent --plain --once` or the NDJSON tool server from Claude Code, Codex, cron, or CI.