# SimpleFunctions Agent Skill

> If this content looks summarized, run:
> `curl -fsSL https://simplefunctions.dev/skill.md`

Prediction market intelligence for AI agents. Live odds from Kalshi and Polymarket, indicator-driven screening, thesis-backed edge detection, traditional market data. No auth required for read endpoints.

## Quick Start

Three ways to connect. Pick one.

### MCP Server (Claude Code / Cursor / Cline)

```bash
claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp
```

54 tools. Includes everything below plus thesis management, trading, portfolio, and evaluation.

### CLI

```bash
npm install -g @spfunctions/cli
sf setup
```

Every command supports `--json` for structured output. Key commands: `sf world`, `sf inspect`, `sf screen`, `sf edges`, `sf ideas`, `sf scan`, `sf ask`, `sf research`. Thesis commands are namespaced: `sf thesis create`, `sf thesis list`, `sf thesis get`. Tool catalog: `sf describe --all --json` (95 tools). Headless mode: `sf agent --headless` exposes tools via stdin/stdout NDJSON — external LLM replaces built-in, zero OpenRouter cost.

### REST API

No auth, no setup. Call directly.

## The Agent Loop

```
1. PERCEIVE  → GET /api/agent/world          → edges, movers, index, divergences (~800 tokens)
2. EVALUATE  → GET /api/agent/inspect/{ticker} → full dossier + suggestion + indicators
3. DISCOVER  → follow nextActions.inspect[]    → drill into related markets
4. ACT       → follow nextActions.execute      → pre-filled POST /api/intents body
```

**Every endpoint returns `nextActions`** with pre-filled API calls. Follow the chain. Add `?nextActions=off` when you no longer need navigation hints.

## No-Auth Endpoints

### Perception — understand what's happening

#### GET /api/agent/world
Salience-ranked snapshot (SPEC-10). Returns Bloomberg-style tiles — regime_shift / divergence / resolving_soon / residual / novel / consensus_break — each with 2-3 per-item pull threads. Self-similar shape at every depth.

```bash
curl -s https://simplefunctions.dev/api/agent/world
curl -s https://simplefunctions.dev/api/agent/world/iran
curl -s https://simplefunctions.dev/api/agent/world/iran/hormuz
curl -s 'https://simplefunctions.dev/api/agent/world?op=catalyst&dt=48h'
curl -s 'https://simplefunctions.dev/api/agent/world/fed-rate?op=dispersion'
curl -s 'https://simplefunctions.dev/api/agent/world?op=trail&from=KXHORMUZTRAFFIC'
curl -s 'https://simplefunctions.dev/api/agent/world?op=explain&item=s-abc123'
```

Ops: `snapshot` (default) | `history` (Δt window) | `catalyst` (upcoming resolutions) | `dispersion` (intra-topic consensus) | `trail` (linkage walk from `from=`) | `explain` (hypothesis candidates for `item=`).

Parameters: `format` (markdown|json), `op`, `dt` (6h|24h|7d), `since` (override baseline), `depth` (0-3), `limit` (1-30, default 10), `from` (for trail), `item` (for explain), `focus` (legacy alias for path drill).

#### GET /api/agent/world/delta?since=1h
Incremental update. Only what changed since timestamp. ~30-50 tokens.

#### GET /api/public/query?q={question}
LLM-enhanced search across Kalshi, Polymarket, X/Twitter, traditional markets, and internal content. Returns structured answer with source markets.

```bash
curl -s 'https://simplefunctions.dev/api/public/query?q=recession+probability+2026'
```

Parameters: `q` (required), `mode` (raw|full), `sources`, `limit` (max 20)

#### GET /api/public/scan?q={keywords}
Cross-venue market search with relevance ranking. Fast (~500ms), no LLM.

```bash
curl -s 'https://simplefunctions.dev/api/public/scan?q=oil&limit=10'
```

Parameters: `q` (required), `limit`, `venue` (kalshi|polymarket), `price_min`, `price_max`, `vol_min`, `expires_before`, `expires_after`

### Inspection — deep-dive a market

#### GET /api/agent/inspect/{ticker}
Complete ticker dossier with actionable suggestion. Price, regime, indicators (IY/CRI/EE/LAS), thesis edges, contagion, 24h diff, 7d trend, and deterministic suggestion (consider_long/short/wait/avoid/monitor).

```bash
curl -s 'https://simplefunctions.dev/api/agent/inspect/KXTRUMPUFC-UFC327'
```

Parameters: `format` (json|markdown), `contagion` (false to skip), `diff` (false), `trend` (false), `nextActions` (off)

Response includes:
- `suggestion` — action, confidence, reasoning, positives, warnings, sizeHint
- `regime` — score 0-1, label (maker/neutral/taker)
- `indicators` — IY (implied yield %), CRI (cliff risk), EE (executable edge), LAS (liquidity-adjusted spread), CVR, overround, tauDays
- `crossVenue` — counterpart on the other exchange
- `nextActions` — pre-filled inspect, query, and execute URLs

### Screening — find opportunities

#### GET /api/public/screen
Indicator screener across the full market universe (~50K markets). Sort by any indicator.

```bash
curl -s 'https://simplefunctions.dev/api/public/screen?sort=iy&limit=10&las_max=0.1'
```

Parameters: `sort` (iy|ee|or|las|cri|tau|volume|price), `order` (asc|desc), `limit` (1-200), `offset`, `keyword`, `venue`, `iy_min`, `iy_max`, `ee_min`, `las_max`, `or_min`, `or_max`, `cri_min`, `cri_max`, `tau_min_days`, `tau_max_days`, `has_thesis`, `has_orderbook`

#### GET /api/public/ideas
S&T-style trade ideas: actionable pitches with conviction, catalyst, direction, risk. Generated daily from 8 data sources.

```bash
curl -s https://simplefunctions.dev/api/public/ideas
```

Parameters: `category` (macro|geopolitics|crypto|policy|event), `limit` (1-10), `q` (on-demand LLM generation for specific topic)

#### GET /api/public/contagion
Cross-market contagion detection. Market A moved — which connected markets haven't caught up? Gap = potential edge.

```bash
curl -s 'https://simplefunctions.dev/api/public/contagion?window=6h'
```

Parameters: `window` (1h|6h|24h|3d), `topic`

### Market Data

#### GET /api/public/index
SF Prediction Market Index v2. Four components: disagreement (realized vol), geoRisk (theater-equal geo basket), breadth (up/down skew), activity (percentile vs 30d).

#### GET /api/public/index/history?days=7
Historical index data. Parameters: `days` (1-30)

#### GET /api/public/newmarkets
Recently listed markets across venues.

Parameters: `hours` (1-720, default 24), `venue`, `limit`, `min_liquidity`

#### GET /api/public/yield-curves
Calendar yield curves — term structure of prediction markets.

Parameters: `limit`, `sort` (default|points_desc|volume_desc)

#### GET /api/calibration
Brier scores on settled markets. T-24h prediction (preferred) + settlement-time fallback. Params: `period` (30d|90d|1y|all), `category`, `min_volume`. Optional Bearer token adds thesis-level calibration alongside global.

#### GET /api/public/highlights
Today's market headlines and highlights.

#### GET /api/public/trad-markets
Traditional market snapshot: SPY, VIX, Gold, Oil, Treasuries via Databento.

#### GET /api/public/market/{ticker}
Complete market profile: price, bid/ask, spread, volume, status, close time, indicators, regime, cross-venue counterpart. Optional orderbook depth.

Parameters: `depth` (boolean), `cv_preset` (arb|world|detail|browse), `cv_min_conf` (0-1 override), `cv_max_dt_days` (override).

#### GET /api/public/cross-venue/pairs
Kalshi × Polymarket matched pairs with LLM-verified confidence. Use for arb surfacing, agent world-state enrichment, or UI counterpart rendering.

```bash
curl -s 'https://simplefunctions.dev/api/public/cross-venue/pairs?preset=arb&limit=10'
curl -s 'https://simplefunctions.dev/api/public/cross-venue/pairs?min_conf=0.85&max_dt_days=30&category=Economics'
curl -s 'https://simplefunctions.dev/api/public/cross-venue/pairs?ticker=KXFEDCHAIR'
```

Presets: `arb` (conf≥0.80, |Δt|≤90d, precision-first) · `world` (conf≥0.75, |Δt|≤180d, agent context) · `detail` (conf≥0.60, lenient) · `browse` (conf≥0.50, permissive).

Parameters: `preset`, `min_conf`, `max_dt_days`, `method` (csv match_method), `category`, `ticker`, `limit` (1-500), `offset`, `order_by` (confidence_desc|dt_asc|recent).

Each pair: `kalshiTicker`, `polyTicker`, `confidenceScore`, `matchMethod`, `direction`, `closeTimeDeltaSec`, `kalshiTitle`, `polyTitle`, `llmRationale`, `isArbReady` (derived: conf≥0.75 AND |Δt|≤90d).

#### GET /api/public/cross-venue/stats
Coverage stats: pair count, confidence histogram with per-bucket arb-ready fraction (`pArbReady`), per-method counts, per-category matched/total ratios.

#### GET /api/public/regime/scan
Markets by adverse selection regime (maker/taker/neutral).

Parameters: `label`, `as_min`, `as_max`, `venue`, `sort`, `limit`

### Content

#### GET /api/public/opinions, /technicals, /glossary
Article collections. Each has `/{slug}` for individual articles.

#### GET /api/public/skills
Agent cognitive skills and workflows. `GET /api/public/skill/{slug}` for individual skill detail.

## Authenticated Endpoints

Requires `Authorization: Bearer sf_live_xxx`. Get a key at https://simplefunctions.dev/dashboard/keys.

### Thesis Management
- `POST /api/thesis/create` — create from **testable claim** (statement that can be true or false at a future date). Rejects reasoning dumps (e.g. "high conviction due to..."), trade verbs ("buy..."), and single keywords. Good: `"Bitcoin closes 2026 above $50,000"`. Bad: `"54-cent cross-venue gap is free money"` (use `/api/thesis/:id/signal` for rationale). Builds causal tree + scans for edges.
- `GET /api/thesis/:id` — full thesis with causal tree, edges, evaluations
- `POST /api/thesis/:id/signal` — inject a signal into monitoring
- `POST /api/thesis/:id/evaluate` — trigger deep evaluation cycle
- `POST /api/thesis/:id/whatif` — override node probabilities, see edge changes (zero LLM cost)

### Execution
- `POST /api/intents` — declare execution intent with trigger conditions
- `GET /api/intents` — list active intents with fill progress
- `GET /api/edges` — top edges across all theses (auth adds private theses)

### Portfolio (MCP / CLI only)
Positions, balance, orders, fills, buy, sell are available via MCP tools and CLI. Not exposed as REST.

## nextActions Pattern

Every endpoint returns a `nextActions` object with pre-filled API calls:

```json
{
  "nextActions": {
    "inspect": [
      { "description": "Oil above $100? @ 43¢", "method": "GET", "url": "/api/agent/inspect/KXWTIMAX-T100" }
    ],
    "related": [
      { "description": "Trade ideas", "method": "GET", "url": "/api/public/ideas" },
      { "description": "Contagion gaps", "method": "GET", "url": "/api/public/contagion" }
    ]
  }
}
```

- `inspect[]` — drill down into specific markets from the current result
- `related[]` — discover other relevant endpoints
- Add `?nextActions=off` to any endpoint to suppress (saves tokens after you know the API)

## Response Format

All endpoints return JSON. Prediction market prices are in cents (0-100), representing implied probability. Traditional market prices are in USD. Edge values = thesis-predicted minus market-observed probability.