Skip to main content

​
Problem

Quant and discretionary trading loops need the same visual primitives that FX, gold, index, and crypto traders use: OHLCV candles, timeframes, recent range, momentum, volatility, and volume. A market search result is not enough to decide whether a contract is tradeable right now. Kalshi and Polymarket also expose large long-tail universes. A bot that scans every market on every tick is too slow and noisy. The SDK needs a first-class K-line surface so users can build watchlist-first scanners and agentic trading loops without touching venue-specific candle APIs.

​
Product surface

Canonical contract: 
market.candles
SDK: 
await sf.markets.candles(ticker, { venue: "kalshi", timeframe: "1m", limit: 500 })
await sf.markets.screenCandles({
  tickers,
  venue: "kalshi",
  timeframes: ["1m", "5m", "15m", "1h"],
  minAbsReturnPct: 2,
  minRangePct: 3,
  minVolume: 100,
  concurrency: 4,
  continueOnError: true,
})
Agent SDK: 
await agent.call("market.candles", { ticker, venue: "kalshi", timeframe: "5m" })
await agent.tools.markets.candles({ ticker, venue: "kalshi", timeframe: "5m" })
HTTP: 
GET /api/public/market/{ticker}/candles?venue=kalshi|polymarket&timeframe=1m&limit=500

​
Semantics

  • Timeframes: 1m, 5m, 15m, 1h, 1d.
  • Venue is optional; explicit values are kalshi and polymarket.
  • Candle fields: t, o, h, l, c, v.
  • Prediction-market prices are normally probabilities in 0..1.
  • market.candles is read-only, but marked costEffect: "venue_request_cost" because cache misses can lazy-load venue history.
  • No live-trade side effects.
  • No CLI dependency.

​
Routing

  • SDK and Agent SDK calls go to the configured SimpleFunctions API base URL. Default: https://simplefunctions.dev on Vercel.
  • Agent SDK tools use the SDK client; they do not shell out to the CLI and do not call a user-local daemon for reads.
  • market.inspect is the contract-info path for price, orderbook depth, spread, and liquidity score. It runs on the SimpleFunctions API server and may use DB/cache, the configured Kalshi orderbook proxy, server-side Kalshi credentials, or Polymarket CLOB depending on venue and deployment config.
  • market.candles enters through the Vercel API route, then proxies to the terminal/Fly candle engine (TERMINAL_BASE, default https://app.simplefunctions.dev).
  • Local execution only happens when the user explicitly sets baseUrl or SF_API_URL to a local or self-hosted SimpleFunctions API.

​
Screening metrics

screenCandles() computes one signal per ticker/timeframe:
  • returnPct
  • absReturnPct
  • rangePct
  • realizedVolatilityPct
  • volume
  • trend
  • breakout
  • score
The helper is intentionally watchlist-first. It does not perform full-market venue crawling. Productized full-universe scanning should use a server-side candle/liquidity index with caching, topic shards, and incremental refresh. Client scans use bounded concurrency by default. continueOnError lets production bots keep ranking the rest of a watchlist when one ticker/timeframe is stale, unsupported, or temporarily unavailable.

​
Non-goals

  • No automatic order placement.
  • No broker-style chart UI in the SDK package.
  • No guarantee that candle screening is alpha.
  • No unbounded venue-wide polling loop inside SDK consumers.

​
Future work

  • Batch candle endpoint for server-side watchlist scans.
  • Cursor/delta support for candle updates.
  • Server-side liquidity index for venue + timeframe + volume + range filters.
  • Agent recipes that combine candles, orderbook depth, external spot feeds, and execution safety gates.