SDK Market Research Patterns

When to use

• Building a TypeScript app that does market search, discovery, or inspection
• Embedding SF market lookup in a custom agent loop
• Producing structured dossiers without shelling out to the CLI

Prerequisites

npm install @spfunctions/[email protected]
export SF_API_KEY="sf_..."  # required for cost-bearing tools

Contract mapping

Search

import { SimpleFunctions } from "@spfunctions/sdk"

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

const results = await sf.markets.search({
  query: "Fed CPI",
  limit: 10,
  venue: "all", // "kalshi" | "polymarket" | "all"
})

console.log(results.markets?.map(market => ({
  ticker: market.ticker,
  venue: market.venue,
  price: market.price,
  title: market.title,
})))

Discover (curated feed)

const discovery = await sf.markets.discover({ limit: 5 })

markets.discover returns the HTTP-backed /api/public/ideas slice — server-curated trade ideas with conviction, catalyst, and direction.

The CLI sf discover --quality --json is broader because it also aggregates local CLI sources (cross-venue pairs, contagion, etc.). For the same breadth via SDK, compose:

const [ideas, pairs, contagion] = await Promise.all([
  sf.markets.discover({ limit: 5 }),
  // Cross-venue pairs and contagion are HTTP-only currently:
  fetch("https://simplefunctions.dev/api/public/cross-venue/pairs?preset=arb&limit=5", {
    headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}` },
  }).then(r => r.json()),
  fetch("https://simplefunctions.dev/api/public/contagion?window=6h&limit=5", {
    headers: { "Authorization": `Bearer ${process.env.SF_API_KEY}` },
  }).then(r => r.json()),
])

Inspect one market

const dossier = await sf.markets.get("KXRECESSION-26DEC31")

console.log({
  ticker: dossier.ticker,
  price: dossier.price,
  spread: dossier.spread,
  liquidity: { vol24h: dossier.volume24h, oi: dossier.openInterest },
  regime: dossier.regime?.label,
  indicators: {
    iy: dossier.indicators?.iyYes,
    cri: dossier.indicators?.cri,
    vr: dossier.indicators?.vr,
    residualVr: dossier.indicators?.residualVr,
  },
  crossVenue: dossier.crossVenue,
})

See sf-inspect skill for indicator interpretation.

History

const history = await sf.markets.history("KXRECESSION-26DEC31")

console.log(history.indicatorHistory?.map(h => ({
  at: h.at,
  price: h.price,
  delta: h.delta,
  iy: h.iy,
})))

Returns 7-day cached price + indicator history. Use this BEFORE citing any specific price in a published claim — the world-API price field can be stale.

Combined research pattern

async function research(topic: string) {
  const [search, world] = await Promise.all([
    sf.markets.search({ query: topic, limit: 5 }),
    sf.world.get(),
  ])
  
  const topMarkets = search.markets ?? []
  const dossiers = await Promise.all(
    topMarkets.slice(0, 3).map(m => sf.markets.get(m.ticker))
  )
  
  return {
    topic,
    regime: world.regime?.label,
    salient: world.salient?.slice(0, 3),
    candidates: dossiers.map(d => ({
      ticker: d.ticker,
      price: d.price,
      spread: d.spread,
      indicators: d.indicators,
    })),
  }
}

const result = await research("Fed rate cuts CPI")
console.log(JSON.stringify(result, null, 2))

This is the SDK equivalent of sf-research workflow skill — parallel search + world + per-market inspect, returned as one structured packet.

Errors

• `HttpError 404` on `get(ticker)`: ticker invalid or market resolved. Use search() to find the correct identifier.
• Empty `markets` array on search: query too narrow. Try broader terms or venue: "all".
• `MissingApiKeyError`: most reads work anonymously, but markets.search and markets.get are cost-bearing.

Related skills

• sf-sdk-quickstart — install + first call
• sf-sdk-world-read — world state pattern
• sf-inspect — CLI-side ticker inspection workflow

Reference docs

• <https://docs.simplefunctions.dev/guides/market-research-sdk>
• <https://docs.simplefunctions.dev/api-reference/market-detail>
• <https://docs.simplefunctions.dev/api-reference/public-market-data>