Skip to main content
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.