SDK · @spfunctions/sdk

Typed market intelligence for apps and agents.

Name: SimpleFunctions
Author: SimpleFunctions

Build dashboards, research jobs, macro monitors, election workflows, and agent runtimes on top of strict SimpleFunctions contracts instead of scraping terminal output or guessing endpoint shape.

install

npm install @spfunctions/sdk@1.0.1

npm latest

key

export SF_API_KEY="sf_..."

identity

inspect

sf.manifest.get("world.read")

contract

read

sf.world.get()

world state

Installnpm install @spfunctions/sdk@1.0.1

Docs·npm·Agent SDK

Five-minute successful path.

The SDK is the plain TypeScript path: construct with `SF_API_KEY`, read the world state, search markets, inspect tickers, and pass that structured context into your own application or model loop.

app.ts

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  baseUrl: "https://simplefunctions.dev",
  apiKey: process.env.SF_API_KEY,
})

const world = await sf.world.get()
const markets = await sf.markets.search({
  query: "Iran oil Strait of Hormuz",
  limit: 5,
})

console.log(world.asOf)
console.table(markets.markets?.map(m => ({
  ticker: m.ticker,
  title: m.title,
  price: m.price,
})))

Strict contracts, not loose endpoints.

`/api/contracts/tools` is the SDK and Agent truth. It uses canonical dotted names like `world.read` and rejects broad compatibility names like `get_world_state`. `/api/tools` remains useful for hosted and MCP compatibility, but it is not the SDK contract.

no-key bootstrap

import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  baseUrl: "https://simplefunctions.dev",
})

const manifest = await sf.manifest.list()
const world = await sf.manifest.get("world.read")
const legacy = await sf.manifest.get("get_world_state")

console.log(manifest.schemaVersion) // 0.3.0-draft
console.log(world?.name)            // world.read
console.log(legacy)                 // null

What you can build.

The SDK is not a generic venue wrapper. It gives TypeScript code the same structured market and world context that SimpleFunctions agents use.

Fund research monitor

world.read → markets.search → market.inspect

Pull world state, search active markets, inspect top tickers, and write the result into an internal dashboard.

Macro policy workflow

world.delta → econ.query → gov.query

Combine economic and government query surfaces with market prices to track CPI, Fed, oil, tariffs, and legislation.

Election office desk

markets.search → market.history → query.ask

Monitor election-related markets, preserve source metadata, and keep analysts on canonical dotted tool names.

Personal agent app

theses.list → watchlists.list → portfolio.state

Attach account-scoped theses, watchlists, alerts, portfolio ticks, and trades behind explicit API-key identity.

API-key-first by design.

No-key mode is for contract inspection only. Useful calls carry identity so rate limits, trace ownership, support, cost effects, and user-data boundaries remain accountable.

No-key bootstrap

manifest.list, manifest.get

Only strict contract inspection is anonymous.

Normal data reads

world.read, world.delta

API-key-first because these are hosted data calls.

Search and LLM reads

markets.search, query.ask

Cost-bearing calls require identity and policy.

User data

portfolio.state, theses.list

Account-scoped reads require API key.

Writes

theses.create, theses.signal

User writes are SDK-only alpha surfaces, not Agent-callable by default.

Use the SDK under Agent v0.

The Agent SDK live runner is built around an API-keyed `SimpleFunctions` client. That keeps execution identity, preflight, typed errors, and request metadata in one place.

sdk-backed agent

import { SimpleFunctions } from "@spfunctions/sdk"
import { SimpleFunctionsAgent } from "@spfunctions/agent"

const sf = new SimpleFunctions({
  baseUrl: "https://simplefunctions.dev",
  apiKey: process.env.SF_API_KEY,
})

const agent = new SimpleFunctionsAgent({
  client: sf,
  policy: {
    maxSideEffect: "none",
    maxCostEffect: "api_cost",
  },
})

Which surface should I use?

SDK

Typed application code

Use in backends, jobs, notebooks, dashboards, and Agent SDK runtimes that need a normal TypeScript client.

Agent SDK v0

Governed direct runner

Use when you want policy, sideEffect/costEffect gates, trace, replay, and canonical tool execution.

Agent SDK v1

Model loop

Use when you want provider-backed query streams, sessions, hooks, watch inputs, and Cursor-style run handles.

CLI

Operator and shell automation

Use from terminals, Claude Code, Codex, cron, CI, and local workflows where shell composition matters.

MCP

Adapter compatibility

Use when a host expects MCP. It is useful, but it is not the strict SDK/Agent contract truth.

Questions.

Is @spfunctions/sdk published?

@spfunctions/sdk is published as 1.0.1 with the npm latest tag. Use the stable package in server-side TypeScript services, jobs, notebooks, and agent harnesses.

Can I use the SDK without an API key?

Only for strict contract inspection, such as manifest.list and manifest.get. Real data, research, user-data, cost-bearing, and side-effecting calls require SF_API_KEY and throw MissingApiKeyError before live HTTP when no key is configured.

How is the SDK different from the CLI?

The SDK is a TypeScript client for applications and embedded runtimes. The CLI is a local operator and automation surface. Use the SDK when you are writing an app; use the CLI when a human, shell script, cron job, or coding agent is driving commands.

How is /api/contracts/tools different from /api/tools?

/api/contracts/tools is the strict SDK and Agent truth with canonical dotted tool names, sideEffect, costEffect, access, agent, and replay metadata. /api/tools is the broader hosted compatibility inventory and includes legacy names that the SDK should not treat as canonical.

Does the SDK place trades?

Live execution is available only through explicit execution surfaces with API-key identity, side-effect policy, cost ceilings, runtime orchestration, and trade guardrails. It is never default-enabled for anonymous or browser clients.