> ## Documentation Index > Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt > Use this file to discover all available pages before exploring further. # Agent API > Compact, agent-shaped reads under /api/agent/* — world snapshot, deltas, ticker dossiers, topic feeds. The first three calls every SimpleFunctions agent makes. `/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: ```text theme={null} get_world_state → pick a ticker inspect_ticker → decide / size / chain to nextActions get_world_delta → refresh on next loop tick ``` ## World snapshot ```http theme={null} 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)** ```json theme={null} { "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 */ } } } ``` ```bash theme={null} # 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 ```http theme={null} 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 ```bash theme={null} curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json" ``` ## Inspect a ticker ```http theme={null} 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** ```json theme={null} { "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. | ```bash theme={null} # 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 ```http theme={null} 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`. | ```bash theme={null} curl "https://simplefunctions.dev/api/agent/feed/fed_rates?since=24h" ``` ## Sub-path routing ```http theme={null} GET /api/agent/world/{...path} ``` Drill into a specific subset of the world snapshot. Examples used by `sf world `: ```bash theme={null} 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`](/cli/agentic-cli) command runs locally. ## See also The agent loop pattern and example flows. Full parameter list for the `/api/agent/world*` family. Auth, base URLs, language examples. `get_world_state`, `inspect_ticker`, `get_world_delta` over MCP.