@spfunctions/sdk

@spfunctions/sdk

Alpha TypeScript SDK for SimpleFunctions.

Install the alpha package:

npm install @spfunctions/sdk@0.1.0-alpha.2

The first accepted vertical slice was:

world.read -> sf.world.get()

The current draft extends the same contract pattern across practical read/research surfaces, authenticated wrappers, and Kalshi-only execution tools. It proves that each surface can be mapped across HTTP API, CLI, SDK, agent tool metadata, permission class, side-effect class, trace event, and docs.

import { SimpleFunctions } from "@spfunctions/sdk"

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

const world = await sf.world.get()
console.log(world.asOf)

SDK examples are API-key-first. sf.manifest.list() and sf.manifest.get(...) can run without a key for strict contract bootstrap; data and research calls such as sf.world.get() are contract-preflighted and require SF_API_KEY when their contract has costEffect or access.anonymousAllowed: false.

Read/research examples:

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")

Market-intelligence examples:

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 at /api/contracts/tools. It uses canonical dotted names such as world.read; broad hosted /api/tools names such as get_world_state are compatibility inventory names, not SDK contract truth.

The SDK exports alpha helper primitives for consumers and the Agent SDK:

• SfRequestMeta plus requestId / traceId propagation on response sources and typed errors.
• SF_CONTRACT_SCHEMA_VERSION, SUPPORTED_CONTRACT_SCHEMA_VERSIONS, and assertSupportedContractManifest(...).
• isSfPage(...), getPageData(...), getNextCursor(...), and hasMore(...) for read wrappers that return SimpleFunctions page envelopes.

Authenticated wrappers:

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.intents.get("intent-id")
await sf.intents.create({
  action: "buy",
  venue: "kalshi",
  marketId: "KXFED-27APR-T3.50",
  marketTitle: "Fed target rate",
  direction: "yes",
  targetQuantity: 1,
  maxPrice: 32,
  autoExecute: true,
})
await sf.intents.cancel("intent-id")
await sf.runtime.status()
await sf.runtime.ensure()
await sf.execution.place({
  ticker: "KXFED-27APR-T3.50",
  action: "buy",
  quantity: 1,
  limitPrice: 32,
})
await sf.watchlists.list()
await sf.alerts.list()

sf.execution.place() is the canonical builder-friendly live execution wrapper. It checks configured runtime candidates, starts or wakes a usable runtime when allowed, then creates the Kalshi intent. Use runtime: { mode: "none" } only when you deliberately want to create an intent without runtime orchestration. live_trade is only an Agent compatibility alias for execution.place.

The SDK has no CLI package dependency. Default runtime orchestration uses the hosted runtime API; local or self-hosted runtimes can be added with runtimeControllers without shelling out to sf.

Package alpha readiness:

• The SDK builds to dist/ for local tarball smoke tests.
• sf.manifest.* is the strict contract manifest; do not treat broad /api/tools names as SDK truth.
• SDK preflight follows the strict contract metadata; no-key access is limited to explicitly anonymous manifest inspection.
• 0.1.0-alpha.2 is published on npm with the alpha dist tag.