> ## 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.

# SDK overview

> TypeScript SDK surfaces mapped to SimpleFunctions contracts.

`@spfunctions/sdk` is published as a stable npm package.

The SDK is a typed wrapper over existing SimpleFunctions HTTP/Data API objects. It does not create a second object model and it does not shell out to the CLI.

```bash theme={null}
npm install @spfunctions/sdk@1.0.1
```

```ts theme={null}
import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL,
})
```

Use the SDK from server-side TypeScript, trusted local scripts, backend jobs, or agent harnesses. Do not expose long-lived `SF_API_KEY` values in browser bundles.

## Read-first surfaces

```ts theme={null}
await sf.world.get()
await sf.world.delta({ since: "1h" })
await sf.markets.discover({ limit: 5 })
await sf.markets.search({ query: "Fed CPI", limit: 10 })
await sf.markets.get("KXRECESSION-26DEC31")
await sf.markets.history("KXRECESSION-26DEC31")
await sf.query.ask({ q: "What are markets saying about recession risk?" })
await sf.econ.query({ q: "unemployment rate", mode: "raw" })
await sf.gov.query({ q: "SAVE Act", mode: "raw" })
await sf.manifest.list()
await sf.manifest.get("world.read")
```

These calls are read-only and map to `sideEffect: none` in the draft contract map.

The market-intelligence resource exposes the existing screening and analytics surfaces:

```ts theme={null}
await sf.intelligence.screen({ iyMin: 20, limit: 10 })
await sf.intelligence.screenByTickers({ tickers: ["KXEXAMPLE"] })
await sf.intelligence.regime({ label: "toxic", limit: 5 })
await sf.intelligence.calendar({ days: 14 })
await sf.intelligence.index()
await sf.intelligence.indexHistory({ days: 30 })
await sf.intelligence.contagion({ window: "6h" })
await sf.intelligence.crossVenuePairs({ preset: "arb", limit: 10 })
await sf.intelligence.crossVenueStats()
await sf.intelligence.yieldCurves({ compact: true })
await sf.intelligence.calibration({ period: "30d" })
```

`sf.manifest.*` reads the strict SDK/Agent contract manifest from `/api/contracts/tools`. It uses canonical dotted names such as `world.read`; broad hosted tool names from `/api/tools`, such as `get_world_state`, are compatibility inventory names and are not SDK contract truth.

The SDK is API-key-first. Manifest inspection is the no-key bootstrap path. Data and research calls are preflighted against the strict contract metadata; if a tool has `costEffect` or `access.anonymousAllowed: false`, the SDK throws `MissingApiKeyError` before the live request when no API key is configured.

## Authenticated reads

```ts theme={null}
await sf.theses.list()
await sf.theses.get("thesis-id")
await sf.portfolio.state()
await sf.portfolio.ticks.list({ limit: 5, envelope: true })
await sf.portfolio.trades.list({ limit: 5, envelope: true })
await sf.intents.list({ active: true })
await sf.watchlists.list()
await sf.alerts.list()
```

Authenticated reads require `SF_API_KEY` or an explicit `apiKey`.

## Not included

The SDK now exposes Kalshi and Polymarket runtime-backed execution through policy-visible contract tools. It still does not implement daemon mode, hosted long-running agents, MCP expansion, or a Python SDK rewrite.

The SDK is also not the Agent SDK. `@spfunctions/agent` is published as a stable package with a Cursor-style `Agent.create().send().stream()` surface for market-intelligence agents. The current `sf agent --tool` CLI path is a command-line wrapper around direct-tool semantics, not the Agent SDK itself.

Agent consumers can let the Agent SDK create the SDK client from an API key:

```ts theme={null}
import { Agent } from "@spfunctions/agent/v1"

const agent = await Agent.create({
  apiKey: process.env.SF_API_KEY,
  openRouterApiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "anthropic/claude-haiku-4.5" },
})

const run = agent.send("Read world state and summarize market moves.")
for await (const event of run.stream()) console.log(event.type)
```

The Agent SDK uses canonical strict tools. It does not use `/api/tools` as truth and does not shell out to the CLI.

## Alpha boundaries

The package exposes the governed strict subset first. `runtime.status`, `runtime.ensure`, `execution.place`, `intents.create`, `intents.get`, and `intents.cancel` are explicit contract tools for Kalshi and Polymarket execution and intent management. `execution.place` uses daemon-aware SDK runtime orchestration before creating an executable intent, without depending on the CLI package. Deferred or hallucination-risk surfaces such as `events.*`, `market.related`, `auth.status`, `investigations.create`, `intents.propose`, and `webhooks.create` stay out of the SDK/Agent default surface until they have explicit contract, auth, side-effect, cost, and policy decisions. The legacy `live_trade` name remains only as a compatibility alias for `execution.place`.