Skip to main content
/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
ParameterTypeDefaultNotes
formatmarkdown | jsonmarkdownMarkdown is compact prose for agent context. JSON is structured.
compacttrue | falsefalseTighter payload — drops verbose narration.
limitintimplementation defaultCap 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
ParameterTypeRequiredNotes
sincestringyesRelative duration (1h, 6h, 24h) or ISO-8601 timestamp.
formatmarkdown | jsonoptionalDefault 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
ParameterTypeNotes
tickerstringKalshi ticker (e.g. KXRATECUT-26DEC31) or Polymarket conditionId.
Query parameters
ParameterTypeDefaultValuesNotes
formatstringjsonjson, markdownjson is structured; markdown is a human-readable dossier.
contagionstringtruetrue, falseInclude cross-market contagion candidates.
diffstringtruetrue, falseInclude the 24h price/indicator diff block.
trendstringtruetrue, falseInclude 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:
ValueMeaning
consider_longBuy the YES contract; the model thinks the implied probability is too low.
consider_shortSell or buy NO; the model thinks the implied probability is too high.
waitSetup is unclear; revisit on next loop.
avoidDon’t trade — low liquidity, settlement risk, or no edge.
monitorWorth 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
StatusBodyCause
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
ParameterTypeNotes
topicstringTopic slug. Use GET /api/public/glossary to list topics.
Query parameters
ParameterTypeDefaultNotes
sincestringoptionalFilter to events after this timestamp / duration.
limitint50Cap on returned items.
formatstringmarkdownmarkdown 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.

​
See also

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.