Kalshi CLI Complete Guide: sf scan, sf positions, sf agent Explained

# Kalshi CLI Complete Guide: sf scan, sf positions, sf agent Explained If you're trading on Kalshi and still navigating the web UI to find markets, check positions, or execute logic-driven trades, you're leaving efficiency on the table. A programmatic approach — scanning markets, filtering by criteria, and running agent loops — is how serious traders operate at scale. [SimpleFunctions](https://simplefunctions.dev) is an agentic runtime built specifically for prediction markets. It wraps Kalshi (and Polymarket) into a CLI, MCP server, REST API, and Telegram bot so you can build and run thesis-driven trading workflows without writing boilerplate from scratch. This guide focuses on the CLI — specifically the three commands you'll use most: `sf scan`, `sf positions`, and `sf agent`. --- ## Installation The CLI is distributed as an npm package. Install it globally: npm install -g @spfunctions/cli Once installed, verify it's working: sf --version sf --help You'll need to authenticate with your Kalshi API credentials. The CLI reads these from environment variables or a local config file. Check the [SimpleFunctions docs](https://simplefunctions.dev/docs) for the full authentication setup, including how to handle key rotation and staging vs. production environments. --- ## sf scan: Finding Markets That Match Your Thesis `sf scan` is the entry point for any research or trading workflow. It queries Kalshi's market catalog and filters the results based on parameters you define — event series, status, volume thresholds, and more. ### Basic Usage sf scan --exchange kalshi This returns all active Kalshi markets. In practice, you'll almost always want to narrow the scope. ### Filtering by Series Kalshi organizes markets into event series using ticker prefixes. To scan only Fed decision markets: sf scan --exchange kalshi --series KXFEDDECISION Or for WTI crude oil max price markets: sf scan --exchange kalshi --series KXWTIMAX For recession-related markets tied to NBER data: sf scan --exchange kalshi --series KXRECSSNBER ### Filtering by Liquidity and Volume Not every market is worth trading. You can filter by minimum open interest or volume: sf scan --exchange kalshi --series KXFEDDECISION --min-volume 10000 This returns only KXFEDDECISION markets where cumulative volume exceeds $10,000 — useful for avoiding thin books where slippage makes execution unreliable. ### Output Formats By default, `sf scan` returns a formatted table to stdout. If you're piping into another tool or logging to a file, use JSON output: sf scan --exchange kalshi --series KXWTIMAX --output json > wti_markets.json This makes `sf scan` composable with `jq`, Python scripts, or any downstream analysis step. ### Practical Scan Workflow Here's a pattern that works well for daily market review: # Scan Fed markets and filter for those closing within 7 days sf scan --exchange kalshi --series KXFEDDECISION --closing-within 7d --min-volume 5000 This surfaces near-term Fed markets with meaningful liquidity — exactly the set you'd want to research before a FOMC meeting. --- ## sf positions: Tracking What You Own Once you're in markets, `sf positions` gives you a real-time view of your open positions, cost basis, current mark, and unrealized P&L across Kalshi. ### Basic Usage sf positions --exchange kalshi This returns all open positions with: - Market ticker - Side (YES/NO) - Quantity - Avg cost - Current mark price - Unrealized P&L ### Filtering Positions If you're running multiple strategies simultaneously, filtering by series keeps things readable: sf positions --exchange kalshi --series KXFEDDECISION Or check only positions that are currently profitable: sf positions --exchange kalshi --min-pnl 0 ### Exporting for Reconciliation sf positions --exchange kalshi --output json > positions_snapshot.json This is useful if you're building a daily reconciliation script or feeding position data into a portfolio tracker. ### Watching Positions Live For active monitoring during volatile periods (pre-FOMC, oil inventory reports, etc.): sf positions --exchange kalshi --watch --interval 30s This polls every 30 seconds and re-renders the position table in place — a lightweight alternative to building a full dashboard for spot checks. --- ## sf agent: Running Thesis-Driven Autonomous Trading This is where SimpleFunctions earns its description as an "agentic runtime." `sf agent` lets you define a trading thesis in natural language or structured YAML, then runs a loop that evaluates markets against that thesis and executes trades when conditions are met. This isn't a simple price-alert bot. The agent can reason about market conditions, compare probabilities against your model, and place or adjust positions accordingly. ### What an Agent Thesis Looks Like A thesis file is a YAML document that specifies: - Which markets to watch - What your probability model says - Entry and exit conditions - Position sizing rules Here's a minimal example for a Fed rate decision thesis: name: fed-hold-q3 exchange: kalshi series: KXFEDDECISION thesis: description: "Fed holds rates unchanged at September meeting" target_markets: - ticker: KXFEDDECISION-23SEP side: YES model_probability: 0.78 entry_threshold: 0.65 # buy YES if market is below 65 cents exit_threshold: 0.85 # close if market reaches 85 cents position_sizing: max_exposure: 500 per_trade: 100 risk: max_loss: 200 Run the agent with this thesis: sf agent --thesis fed-hold-q3.yaml --dry-run The `--dry-run` flag is critical when testing. It executes the full agent loop — evaluating markets, computing whether thresholds are met — but stops before placing any orders. Always validate thesis logic with `--dry-run` before live execution. ### Running Live sf agent --thesis fed-hold-q3.yaml --interval 5m This runs the agent loop every 5 minutes, checking whether market prices have crossed your entry or exit thresholds. ### Multi-Market Agents Agents can span multiple tickers within a series. Here's a more complex thesis across WTI markets: name: wti-range-bound exchange: kalshi thesis: description: "WTI stays between $70-$80 through end of month" target_markets: - ticker: KXWTIMAX-JUL side: NO model_probability: 0.72 entry_threshold: 0.60 - ticker: KXWTIMAX-AUG side: NO model_probability: 0.68 entry_threshold: 0.58 position_sizing: max_exposure: 1000 per_trade: 200 correlate: true # treat as correlated, size accordingly The `correlate: true` flag tells the agent to treat these positions as correlated risk — it won't scale them independently as if they were uncorrelated bets. ### Agent Logging and Monitoring Agent runs produce structured logs you can tail or ship to a log aggregator: sf agent --thesis wti-range-bound.yaml --log-level debug --log-file ./agent.log Each loop iteration logs: - Current market prices - Model vs. market probability delta - Whether thresholds are met - Any orders placed or rejected - Current exposure vs. limits For a more visual overview during active runs, the `sf dashboard` command renders a terminal UI that shows agent status, live positions, and recent trade activity side by side. --- ## Combining the Commands: A Practical Workflow These three commands work best as a pipeline, not in isolation. Here's how a typical workflow looks in practice: **Step 1: Scan for opportunities** sf scan --exchange kalshi --series KXRECSSNBER --min-volume 8000 --output json > recession_markets.json **Step 2: Review positions before adding exposure** sf positions --exchange kalshi --series KXRECSSNBER **Step 3: Define and validate a thesis** sf agent --thesis recession-q4.yaml --dry-run **Step 4: Run live with a conservative interval** sf agent --thesis recession-q4.yaml --interval 15m --log-file ./recession-agent.log This flow keeps research, risk review, and execution clearly separated — which matters when you're running multiple agents across different market series simultaneously. --- ## Using the MCP Server for IDE Integration If you're building custom tooling or want to integrate prediction market data into an LLM-powered workflow, SimpleFunctions also ships an MCP (Model Context Protocol) server. This lets you call `sf scan`, `sf positions`, and agent controls from within Claude, Cursor, or any MCP-compatible client. The full setup is covered in the [SimpleFunctions guide](https://simplefunctions.dev/docs/guide), including how to expose the server locally and configure tool permissions. --- ## Common Pitfalls and How to Avoid Them **Running agents without dry-run validation** Always test thesis files with `--dry-run` first. A misconfigured threshold or ticker typo can result in unexpected orders. The dry-run output shows exactly what the agent would have done — review it carefully. **Ignoring correlation between positions** If you're running agents on KXFEDDECISION and KXRECSSNBER simultaneously, those markets are correlated. A hawkish Fed surprise moves both. If you're not accounting for that in position sizing, you're taking on more correlated risk than your per-market limits suggest. **Not setting max_loss limits** The `risk.max_loss` field in agent YAML is not optional in practice. Without it, a bad thesis combined with a volatile market can exhaust your account faster than the polling interval catches it. Set conservative limits until you've validated agent behavior over several cycles. **Using default output format in scripts** The human-readable table output is great for terminals, but if you're piping `sf scan` or `sf positions` into another process, always use `--output json`. Parsing table formatting is fragile and breaks across CLI version updates. --- ## What's Next The CLI is the fastest way to get started, but SimpleFunctions also exposes everything via REST API if you want to integrate prediction market operations into an existing application or trading infrastructure. The Telegram bot is a lightweight alternative for monitoring agent status and receiving position alerts without keeping a terminal open. For the full command reference, flag documentation, and YAML schema for thesis files, the [SimpleFunctions documentation](https://simplefunctions.dev/docs) is the authoritative source — it's kept up to date with each CLI release. Kalshi's market catalog keeps expanding — energy, macro, crypto, and geopolitical series are all active and liquid enough to trade systematically. The infrastructure to do that efficiently, without rebuilding it from scratch for every new thesis, is what the SimpleFunctions CLI is designed to provide.