SimpleFunctions Developer Manual

SimpleFunctions APIs expose prediction markets as structured state. For a build-oriented walkthrough with curl, TypeScript, and Python examples, start with Direct API access. Base URL:

https://simplefunctions.dev

Surface groups

Group	Prefix	Auth	Purpose
Query and public markets	`/api/public/*`	no auth for public reads	Search, screens, market detail, index, gov/econ context
Agent world	`/api/agent/*`	no auth for core reads	Compact world state, deltas, feed, inspect
Account	`/api/thesis`, `/api/feed`, `/api/intents`, `/api/keys`	API key	User-owned theses, feed, intents, API keys
Portfolio	`/api/portfolio/*`	API key	Portfolio state, ticks, trades, config, views, strategies
Workflow state	`/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints`	API key	User-owned watched objects, alert rules, webhook endpoints

First calls

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://simplefunctions.dev/api/contracts/tools"

Authentication

Public market and world-state endpoints do not require auth for core reads. On supported routes, auth may unlock higher rate limits, higher model tiers, or user-specific overlays. Authenticated endpoints use a SimpleFunctions API key:

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

Authenticated reads are scoped to the authenticated user. Do not pass arbitrary userId fields from the client for normal account or portfolio reads.

Common response style

Public endpoints generally return the documented object directly. Account and portfolio surfaces use a stable envelope where appropriate:

{
  "ok": true,
  "data": {},
  "meta": {}
}

Errors should be structured:

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "status": 401
  }
}

Choosing the right endpoint

User question	Endpoint
”What markets match this real-world event?”	`GET /api/public/query?q=`
”What should an agent know about the world right now?”	`GET /api/agent/world`
”What changed since the last loop?”	`GET /api/agent/world/delta?since=`
”What is the full state of this ticker?”	`GET /api/public/market/{ticker}` or `GET /api/agent/inspect/{ticker}`
”What official economic/government context maps to this topic?”	`GET /api/public/query-econ?q=` or `GET /api/public/query-gov?q=`
”What user-owned portfolio history can this agent see?”	`GET /api/portfolio/ticks` and related portfolio endpoints
”What canonical SDK/Agent tools exist?”	`GET /api/contracts/tools`
”What broad hosted compatibility tools exist?”	`GET /api/tools`
”How do I call the API from my service?”	Direct API access

Tool catalogs

Use the right catalog for the job:

Catalog	Meaning
`GET /api/contracts/tools`	Strict SDK/Agent contract truth: canonical dotted tools, auth, access, `sideEffect`, `costEffect`, Agent callability, replay metadata.
`GET /api/tools`	Broad hosted compatibility inventory for HTTP-native and MCP-adjacent clients.
`sf describe --all --json`	Local installed CLI command manifest.

SDK and Agent SDK code should use /api/contracts/tools. Broad names such as get_world_state are compatibility names, not SDK/Agent canonical tool names.

Start with the API

Public market APIs

Authenticated APIs

Tools and events

REST API

Surface groups

First calls

Authentication

Common response style

Choosing the right endpoint

Tool catalogs

​Surface groups

​First calls

​Authentication

​Common response style

​Choosing the right endpoint

​Tool catalogs

Surface groups

First calls

Authentication

Common response style

Choosing the right endpoint

Tool catalogs