> ## 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 screening loop

> Build a watchlist-first K-line scanner with the SDK, then hand the ranked packet to an agent or trader.

This recipe is the short-term market-data layer for a trader or quant bot. It ranks a finite watchlist across multiple timeframes, then inspects the top contracts for orderbook depth and liquidity before any execution policy can act.

## Install

```bash theme={null}
npm init -y
npm install @spfunctions/sdk@1.0.1
export SF_API_KEY="sf_..."
```

## Script

```ts theme={null}
import { writeFile } from "node:fs/promises"
import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  baseUrl: "https://simplefunctions.dev",
  apiKey: process.env.SF_API_KEY,
})

const watchlist = [
  "KXBTCD-26MAY1917-T76499.99",
  "KXINXU-26MAY19H1600-T7374.9999",
  "KXWTI-26MAY1914-T104.99",
]

const screen = await sf.markets.screenCandles({
  venue: "kalshi",
  tickers: watchlist,
  timeframes: ["1m", "5m", "15m", "1h"],
  limit: 300,
  minBars: 20,
  minAbsReturnPct: 2,
  minRangePct: 3,
  sort: "score",
  concurrency: 4,
  continueOnError: true,
  maxResults: 10,
})

const enriched = []
for (const signal of screen.signals.slice(0, 5)) {
  const market = await sf.markets.get(signal.ticker, {
    venue: signal.venue,
    depth: true,
    nextActions: false,
  })

  enriched.push({
    ...signal,
    title: market.title,
    bestBid: market.bestBid,
    bestAsk: market.bestAsk,
    spread: market.spread,
    liquidityScore: market.liquidityScore,
    bidLevels: market.bidLevels?.slice(0, 3),
    askLevels: market.askLevels?.slice(0, 3),
  })
}

const packet = {
  generatedAt: new Date().toISOString(),
  routing: {
    sdkBaseUrl: "https://simplefunctions.dev",
    candles: "Vercel API -> terminal/Fly candle service",
    inspect: "Vercel API -> DB/cache/proxy/venue reads",
  },
  signals: enriched,
  warnings: screen.warnings,
}

await writeFile("candle-screen.json", JSON.stringify(packet, null, 2))
console.log(JSON.stringify(packet, null, 2))
```

## Production notes

* Keep `tickers` finite. Full-universe scans should run through a server-side index, not unbounded client polling.
* Use `continueOnError: true` so one stale ticker does not stop the whole scan.
* Inspect orderbook depth before trading from a candle signal.
* Combine this packet with risk limits, settlement checks, external references, and explicit execution guardrails.

## Next steps

<CardGroup cols={2}>
  <Card title="Market candles guide" href="/guides/market-candles-sdk">
    Read the canonical SDK and Agent SDK API shape.
  </Card>

  <Card title="Agent trader loop" href="/cookbook/agent-trader-loop">
    Add policy-gated execution after research and risk checks.
  </Card>
</CardGroup>