@spfunctions/sdk

@spfunctions/sdk

TypeScript SDK for SimpleFunctions.

Install the stable package:

npm install @spfunctions/sdk@1.0.0

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 plus Polymarket runtime-backed 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.markets.candles("KXBTCD-26MAY1917-T76499.99", { timeframe: "1m", limit: 500 })
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" })

Watchlist-first candle screening:

const movers = await sf.markets.screenCandles({
  tickers: ["KXBTCD-26MAY1917-T76499.99", "KXWTI-26MAY1914-T104.99"],
  timeframes: ["1m", "5m", "15m", "1h"],
  minBars: 20,
  minVolume: 100,
  minAbsReturnPct: 2,
  minRangePct: 3,
  sort: "score",
})

sf.markets.candles() returns OHLCV/K-line bars for 1m, 5m, 15m, 1h, and 1d. Pass venue: "kalshi" or venue: "polymarket" when the market id is ambiguous. screenCandles() runs with bounded concurrency and ranks ticker/timeframe signals by return, range, realized volatility, volume, trend, breakout, and score.

Routing: SDK and Agent SDK calls go to the configured SimpleFunctions API base URL. Default is https://simplefunctions.dev on Vercel. market.inspect returns contract price/orderbook/liquidity from the API server, which may use DB/cache plus server-side venue/proxy reads. market.candles enters through Vercel and then proxies to the terminal/Fly candle service. The SDK does not call venue APIs, the CLI, or a local runtime directly unless you set baseUrl / SF_API_URL to your own SimpleFunctions API.

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 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.create({
  action: "buy",
  venue: "polymarket",
  marketId: "POLYMARKET_CLOB_TOKEN_ID",
  marketTitle: "Polymarket event outcome",
  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.execution.place({
  venue: "polymarket",
  tokenId: "POLYMARKET_CLOB_TOKEN_ID",
  action: "buy",
  quantity: 1,
  limitPrice: 32,
})
await sf.watchlists.list()
await sf.watchlists.add({ ticker: "KXFED-27APR-T3.50" })
await sf.alerts.list()
await sf.alerts.create({
  watch: "KXFED-27APR-T3.50",
  type: "price_above",
  threshold: 60,
  idempotencyKey: "agent-run-123:fed-alert",
})

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 or Polymarket intent. Polymarket requires a CLOB token id and an explicit limitPrice/maxPrice; the runtime performs venue signing with user-configured exchange credentials. 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 release readiness:

• The SDK builds to dist/ for local tarball smoke tests.
• The SDK package publishes only dist/ and README.md; build output omits source maps and declaration maps.
• 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.
• 1.0.0 is published on npm with the latest dist tag.