SimpleFunctions Developer Manual

market.candles is the SDK and Agent SDK contract for trader-style OHLCV bars. It is read-only, but it may lazy-load venue candle history, so SDK callers need SF_API_KEY. Supported timeframes:

1m, 5m, 15m, 1h, 1d

Read one chart

import { SimpleFunctions } from "@spfunctions/sdk"

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

const chart = await sf.markets.candles("KXBTCD-26MAY1917-T76499.99", {
  venue: "kalshi",
  timeframe: "1m",
  limit: 500,
})

console.log(chart.candles.at(-1))

Each candle uses compact trading-terminal fields:

type MarketCandle = {
  t: number // Unix seconds
  o: number // open
  h: number // high
  l: number // low
  c: number // close
  v: number // volume
}

For prediction markets, price values are usually probabilities in 0..1. Convert to cents with price * 100 when you want venue-style cent display. Omit venue for server-side auto-resolution, or pass kalshi or polymarket when the market id is ambiguous.

Screen multiple timeframes

Use screenCandles() when you already have a watchlist and want a trader-style scan for movement, range, volatility, and volume.

const screen = await sf.markets.screenCandles({
  venue: "kalshi",
  tickers: [
    "KXBTCD-26MAY1917-T76499.99",
    "KXINXU-26MAY19H1600-T7374.9999",
    "KXWTI-26MAY1914-T104.99",
  ],
  timeframes: ["1m", "5m", "15m", "1h"],
  limit: 300,
  minBars: 20,
  minVolume: 100,
  minAbsReturnPct: 2,
  minRangePct: 3,
  trend: "any",
  sort: "score",
  concurrency: 4,
  continueOnError: true,
  maxResults: 20,
})

for (const signal of screen.signals) {
  console.log(signal.ticker, signal.timeframe, signal.trend, signal.returnPct, signal.rangePct)
}

screenCandles() is a client-side SDK helper. It calls market.candles for each ticker and timeframe, then computes:

returnPct
absReturnPct
rangePct
realizedVolatilityPct
volume
trend
breakout
score

This is a screening layer, not a trading signal. A live bot should pair it with venue depth, settlement rules, external price feeds, and policy gates before execution. screenCandles() runs with bounded concurrency. Use concurrency to tune watchlist scans and continueOnError: true when one stale or unsupported market should not stop the whole scan.

Agent SDK

Direct Agent SDK callers can use the same canonical tool:

const result = await agent.call("market.candles", {
  ticker: "KXBTCD-26MAY1917-T76499.99",
  venue: "kalshi",
  timeframe: "5m",
  limit: 200,
})

The ergonomic wrapper is:

await agent.tools.markets.candles({
  ticker: "KXBTCD-26MAY1917-T76499.99",
  venue: "kalshi",
  timeframe: "5m",
})

API mapping

market.candles -> GET /api/public/market/{ticker}/candles?venue=kalshi|polymarket&timeframe=1m&limit=500

The SDK does not call the CLI. The hosted API proxies the same candle engine used by the terminal and normalizes the endpoint into the strict SDK and Agent SDK contract map. By default, SDK and Agent SDK callers send this request to https://simplefunctions.dev, the Vercel API surface. That route proxies candle reads to the terminal/Fly data service at TERMINAL_BASE or https://app.simplefunctions.dev. Set baseUrl or SF_API_URL only when you want to target a local or self-hosted SimpleFunctions API.

Choose a package

SDK quickstarts

Agent contracts

Market candles and K-line screening

Read one chart

Screen multiple timeframes

Agent SDK

API mapping

​Read one chart

​Screen multiple timeframes

​Agent SDK

​API mapping

Read one chart

Screen multiple timeframes

Agent SDK

API mapping