> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK candle and K-line screening spec

> Product spec for adding trader-style OHLCV candles and multi-timeframe screening to the SDK and Agent SDK.

## 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:

```text theme={null}
market.candles
```

SDK:

```ts theme={null}
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:

```ts theme={null}
await agent.call("market.candles", { ticker, venue: "kalshi", timeframe: "5m" })
await agent.tools.markets.candles({ ticker, venue: "kalshi", timeframe: "5m" })
```

HTTP:

```text theme={null}
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.