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

# Market candles and K-line screening

> Use the SDK and Agent SDK to read OHLCV candles across timeframes and rank short-term market moves.

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

```text theme={null}
1m, 5m, 15m, 1h, 1d
```

## Read one chart

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

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

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

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

The ergonomic wrapper is:

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

## API mapping

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