SimpleFunctions Developer Manual

Use direct API access when a service, dashboard, research notebook, or agent runtime needs stable HTTP calls instead of shelling out to sf. Prefer the CLI when a local agent wants tool discovery, local config, command policy tags, or sf describe --all --json as its control plane. Use MCP only as the final adapter when the host requires Model Context Protocol.

Base URLs

Surface	URL
Core API	`https://simplefunctions.dev`
Data REST	`https://data.simplefunctions.dev/v1`
Data WebSocket	`wss://app.simplefunctions.dev/ws`

Do not use wss://data.simplefunctions.dev/v1/ws as the public WebSocket URL unless the real-time data page says it has moved.

Auth matrix

Surface	Auth	Notes
`/api/public/*`	Usually no auth for public reads	Auth may unlock higher limits, higher model tiers, or user overlays on supported routes.
`/api/agent/world`, `/api/agent/inspect/*`	No auth for core reads	Compact payloads for agents.
`/api/contracts/tools`	No auth	Strict SDK/Agent contract manifest.
`/api/tools`	No auth	Broad hosted compatibility inventory.
`/api/thesis/*`, `/api/feed`, `/api/intents`, `/api/keys`	`Authorization: Bearer sf_live_...`	User-owned data.
`/api/portfolio/*`	`Authorization: Bearer sf_live_...`	User-scoped portfolio memory and config.
`/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints`	`Authorization: Bearer sf_live_...`	User-owned workflow state.
`data.simplefunctions.dev/v1`	See Real-time data	Data API auth is documented separately.

First curl calls

Public reads:

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"
curl "https://simplefunctions.dev/api/agent/world?format=json"
curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json"
curl "https://simplefunctions.dev/api/public/market/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/public/query-econ?q=unemployment%20rate&includeMarkets=true"
curl "https://simplefunctions.dev/api/public/query-gov?q=SAVE%20Act&limit=3"
curl "https://simplefunctions.dev/api/contracts/tools"

Authenticated user-owned reads:

curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/thesis"

curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/portfolio/state"

TypeScript

type SfFetchOptions = RequestInit & { apiKey?: string }

async function sfFetch<T>(path: string, options: SfFetchOptions = {}): Promise<T> {
  const { apiKey, headers, ...init } = options
  const res = await fetch(`https://simplefunctions.dev${path}`, {
    ...init,
    headers: {
      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
      ...headers,
    },
  })

  const text = await res.text()
  const body = text ? JSON.parse(text) : null

  if (!res.ok) {
    throw new Error(body?.error?.message ?? body?.message ?? `SimpleFunctions HTTP ${res.status}`)
  }

  return body as T
}

const markets = await sfFetch('/api/public/query?q=Fed%20rate%20cut&limit=3')

const portfolio = await sfFetch('/api/portfolio/state', {
  apiKey: process.env.SF_API_KEY,
})

Python

import os
import requests

BASE = "https://simplefunctions.dev"

query = requests.get(
    f"{BASE}/api/public/query",
    params={"q": "Fed rate cut", "limit": 3},
    timeout=20,
)
query.raise_for_status()
print(query.json())

portfolio = requests.get(
    f"{BASE}/api/portfolio/state",
    headers={"Authorization": f"Bearer {os.environ['SF_API_KEY']}"},
    timeout=20,
)
portfolio.raise_for_status()
print(portfolio.json())

Responses and errors

Public endpoints generally return endpoint-specific JSON directly. Account, portfolio, and workflow endpoints often use { ok, ... } envelopes where documented. Always branch on HTTP status first. Do not scrape prose from rendered docs or terminal output. Prefer format=json where a route supports it.

Endpoint chooser

Need	Endpoint
Find markets for a natural-language event	`GET /api/public/query?q=`
Get compact world context	`GET /api/agent/world?format=json`
Get changes since last loop	`GET /api/agent/world/delta?since=1h&format=json`
Inspect one ticker	`GET /api/agent/inspect/{ticker}`
Get one market detail	`GET /api/public/market/{ticker}`
Search official econ context	`GET /api/public/query-econ?q=`
Search gov or legislative context	`GET /api/public/query-gov?q=`
Discover canonical SDK/Agent tools	`GET /api/contracts/tools`
Discover broad hosted compatibility tools	`GET /api/tools`
Read user portfolio memory	`GET /api/portfolio/state`, `/ticks`, `/trades`
Create user workflow notifications	`/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints`

SDK and Agent contract note

If you are building against the TypeScript SDK or Agent SDK packages, use /api/contracts/tools for canonical tools. /api/tools remains a broad hosted inventory for compatibility and remote HTTP discovery.

Safety notes

API keys are secrets. Do not paste them into prompts, public logs, or client-side bundles. Execution endpoints can mutate real account state. Prediction markets are probabilities, not guarantees. User-owned endpoints are scoped to the authenticated user; do not pass userId for normal reads.

Start with the API

Public market APIs

Authenticated APIs

Tools and events

Direct API access

Base URLs

Auth matrix

First curl calls

TypeScript

Python

Responses and errors

Endpoint chooser

SDK and Agent contract note

Safety notes

​Base URLs

​Auth matrix

​First curl calls

​TypeScript

​Python

​Responses and errors

​Endpoint chooser

​SDK and Agent contract note

​Safety notes

Base URLs

Auth matrix

First curl calls

TypeScript

Python

Responses and errors

Endpoint chooser

SDK and Agent contract note

Safety notes