SimpleFunctions Developer Manual

/api/agent/* is the agent loop surface: every endpoint is shaped for an LLM context window — fewer fields than the raw /api/public/* reads, with nextActions links so the agent can chain calls. Auth is optional; an authenticated request adds a portfolio overlay where supported. The canonical loop is:

get_world_state    →  pick a ticker
inspect_ticker     →  decide / size / chain to nextActions
get_world_delta    →  refresh on next loop tick

World snapshot

GET /api/agent/world

Auth: optional. Anonymous returns the full world; authenticated adds a portfolio overlay (portfolio.positions, portfolio.exposureByCategory) and stamps each opportunity with alreadyPositioned, currentPositionSize, currentPositionDirection. Query parameters

Parameter	Type	Default	Notes
`format`	`markdown` \| `json`	`markdown`	Markdown is compact prose for agent context. JSON is structured.
`compact`	`true` \| `false`	`false`	Tighter payload — drops verbose narration.
`limit`	int	implementation default	Cap on opportunity count.

Response (json)

{
  "index": { "value": 47.2, "delta24h": -1.6, "components": { /* ... */ } },
  "opportunities": [
    {
      "ticker": "KXRATECUT-26DEC31",
      "kind": "high_yield",
      "summary": "...",
      "price": 49,
      "yieldPct": 12.4,
      "alreadyPositioned": false
    }
  ],
  "movers": [ /* sorted by absolute price change */ ],
  "stableAnchors": [ /* low-vol high-volume markets */ ],
  "divergences": [ /* venue-vs-venue gaps */ ],
  "regimeSummary": { "calm": 41, "active": 12, "stressed": 3 },
  "portfolio": {
    "positions": [ /* only if authenticated */ ],
    "exposureByCategory": { /* only if authenticated */ }
  }
}

# anonymous, markdown for agent context
curl "https://simplefunctions.dev/api/agent/world"

# authenticated, JSON, with portfolio overlay
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/agent/world?format=json"

World delta

GET /api/agent/world/delta

Incremental update — only what changed. Typical payload is 30-50 tokens instead of 800 for the full snapshot. Use this for refresh inside a long-running agent loop. Auth: none required. Query parameters

Parameter	Type	Required	Notes
`since`	string	yes	Relative duration (`1h`, `6h`, `24h`) or ISO-8601 timestamp.
`format`	`markdown` \| `json`	optional	Default `markdown`.

Response shape

SimpleFunctions Index changes (indexDelta)
New / dropped market movers (movers.added, movers.dropped)
Position-level alerts when authenticated
Resolutions or settlements that occurred in the window

curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json"

Inspect a ticker

GET /api/agent/inspect/{ticker}

Step 2 of the agent loop. Pass any ticker from get_world_state (or any Kalshi ticker / Polymarket conditionId). The dossier returns a recommended action and pre-filled nextActions so the agent can chain into intent creation, alert setup, or related-market drill-down without composing URLs by hand. Auth: none required for the core read. Authenticated callers see position-aware overlays. Path parameters

Parameter	Type	Notes
`ticker`	string	Kalshi ticker (e.g. `KXRATECUT-26DEC31`) or Polymarket `conditionId`.

Query parameters

Parameter	Type	Default	Values	Notes
`format`	string	`json`	`json`, `markdown`	`json` is structured; `markdown` is a human-readable dossier.
`contagion`	string	`true`	`true`, `false`	Include cross-market contagion candidates.
`diff`	string	`true`	`true`, `false`	Include the 24h price/indicator diff block.
`trend`	string	`true`	`true`, `false`	Include the 7d trend block.

Response (json) — structured dossier

{
  "ticker": "KXRATECUT-26DEC31",
  "venue": "kalshi",
  "title": "Will the Federal Reserve cut rates before 2027?",
  "price": 49,
  "bestBid": 48,
  "bestAsk": 50,
  "volume24h": 102746.28,
  "openInterest": 412390,
  "suggestion": {
    "action": "consider_long" | "consider_short" | "wait" | "avoid" | "monitor",
    "confidence": 0.62,
    "reasoning": "...",
    "positives": ["..."],
    "warnings": ["..."],
    "sizeHint": "small" | "medium" | "large"
  },
  "regime": { "label": "active", "asScore": 0.71, "signals": [/* ... */] },
  "indicators": { "iy": 0.04, "cri": 0.18, "ee": 0.22, "las": 0.55, "tau": 6 },
  "edges": [ /* SimpleFunctions-modelled mispricings */ ],
  "crossVenue": [ /* matched markets on the other venue */ ],
  "contagion": [ /* connected markets that should move with this one */ ],
  "diff24h": { "priceDelta": +3, "yieldDelta": -1.2, "...": "..." },
  "trend7d": { "series": [/* daily points */] },
  "nextActions": {
    "execute": "POST https://simplefunctions.dev/api/intents",
    "watch": "POST https://simplefunctions.dev/api/watch",
    "deeper": [
      "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-27DEC31",
      "https://simplefunctions.dev/api/agent/inspect/KXFEDDECISION-26DEC-CUT100"
    ]
  }
}

suggestion.action is the agent-actionable primitive — five values:

Value	Meaning
`consider_long`	Buy the YES contract; the model thinks the implied probability is too low.
`consider_short`	Sell or buy NO; the model thinks the implied probability is too high.
`wait`	Setup is unclear; revisit on next loop.
`avoid`	Don’t trade — low liquidity, settlement risk, or no edge.
`monitor`	Worth tracking but not actionable now; subscribe to deltas.

# JSON dossier for an agent
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"

# human-readable dossier
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?format=markdown"

# trim payload
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?contagion=false&trend=false"

Errors

Status	Body	Cause
`400`	`{ "error": "ticker required" }`	Empty path segment.
`404`	`{ "error": "Market not found" }`	Unknown ticker / conditionId.
`502`	`{ "error": "Upstream venue error" }`	Kalshi or Polymarket upstream failure.

Topic feed

GET /api/agent/feed/{topic}

A topic-scoped activity slice — markets, theses, ideas, opinions, legislation tagged with the topic, ordered most-recent-first. Useful when an agent is monitoring one domain (e.g. fed_rates, ukraine). Path parameters

Parameter	Type	Notes
`topic`	string	Topic slug. Use `GET /api/public/glossary` to list topics.

Query parameters

Parameter	Type	Default	Notes
`since`	string	optional	Filter to events after this timestamp / duration.
`limit`	int	`50`	Cap on returned items.
`format`	string	`markdown`	`markdown` or `json`.

curl "https://simplefunctions.dev/api/agent/feed/fed_rates?since=24h"

Sub-path routing

GET /api/agent/world/{...path}

Drill into a specific subset of the world snapshot. Examples used by sf world <path>:

curl "https://simplefunctions.dev/api/agent/world/iran"
curl "https://simplefunctions.dev/api/agent/world/iran/hormuz"
curl "https://simplefunctions.dev/api/agent/world/macro"

The path segments map to topic / region / theme axes. Returns the same world shape filtered to the matched scope.

Why `/api/agent/` instead of `/api/public/`

Same data, different shape:

`/api/public/*`	`/api/agent/*`
Raw JSON, full fields.	Compact, drops fields agents don’t read.
No `nextActions`.	`nextActions[]` for chained calls.
One topic per endpoint.	Multi-topic in one call (`world`, `delta`, `inspect`).
Best for dashboards / data integrations.	Best for LLM-driven flows — saves tokens.

Token budget guidance

For a 200k-context model running a long loop:

Boot: get_world_state (full snapshot once)
Loop tick: get_world_delta?since=1h (30-50 tokens)
Drill: get_inspect_ticker/{ticker} only when scoring requires depth

This is the same loop the sf agent command runs locally.

World model guide

The agent loop pattern and example flows.

World state API

Full parameter list for the /api/agent/world* family.

Direct API access

Auth, base URLs, language examples.

MCP tools

get_world_state, inspect_ticker, get_world_delta over MCP.

Start with the API

Public market APIs

Authenticated APIs

Tools and events

Agent API

World snapshot

World delta

Inspect a ticker

Topic feed

Sub-path routing

Why `/api/agent/` instead of `/api/public/`

Token budget guidance

See also

World model guide

World state API

Direct API access

MCP tools

​World snapshot

​World delta

​Inspect a ticker

​Topic feed

​Sub-path routing

​Why /api/agent/* instead of /api/public/*

​Token budget guidance

​See also

World model guide

World state API

Direct API access

MCP tools

World snapshot

World delta

Inspect a ticker

Topic feed

Sub-path routing

Why `/api/agent/` instead of `/api/public/`

Token budget guidance

See also