Skip to main content
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

SurfaceURL
Core APIhttps://simplefunctions.dev
Data RESThttps://data.simplefunctions.dev/v1
Data WebSocketwss://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

SurfaceAuthNotes
/api/public/*Usually no auth for public readsAuth may unlock higher limits, higher model tiers, or user overlays on supported routes.
/api/agent/world, /api/agent/inspect/*No auth for core readsCompact payloads for agents.
/api/contracts/toolsNo authStrict SDK/Agent contract manifest.
/api/toolsNo authBroad hosted compatibility inventory.
/api/thesis/*, /api/feed, /api/intents, /api/keysAuthorization: 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-endpointsAuthorization: Bearer sf_live_...User-owned workflow state.
data.simplefunctions.dev/v1See Real-time dataData 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

NeedEndpoint
Find markets for a natural-language eventGET /api/public/query?q=
Get compact world contextGET /api/agent/world?format=json
Get changes since last loopGET /api/agent/world/delta?since=1h&format=json
Inspect one tickerGET /api/agent/inspect/{ticker}
Get one market detailGET /api/public/market/{ticker}
Search official econ contextGET /api/public/query-econ?q=
Search gov or legislative contextGET /api/public/query-gov?q=
Discover canonical SDK/Agent toolsGET /api/contracts/tools
Discover broad hosted compatibility toolsGET /api/tools
Read user portfolio memoryGET /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.