dflow-kalshi-market-scanner

Files (1)

• SKILL.md

SKILL.md (first lines)

# DFlow Kalshi Market Scanner

Find Kalshi markets that match a **criterion**. This skill is a set of named **scans** (filter-and-rank recipes) over the DFlow Metadata API.

## Prerequisites

- **DFlow docs MCP** (`https://pond.dflow.net/mcp`) — install per the [repo README](../../README.md#recommended-install-the-dflow-docs-mcp). This skill is the recipe; the MCP is the reference. Look up exact query params, pagination, response shapes, and anything else field-level via `search_d_flow` / `query_docs_filesystem_d_flow` — don't guess.

## Surface

All scans here run against the **Metadata API** (`https://pond.dflow.net/build/metadata-api`) — REST for point-in-time queries, WebSockets for continuous streams. You can call both from anywhere: a quick `curl` from the command line, a Node/Python script, a cron job, a backend service, or a Next.js route proxying a browser UI.

If the user says "run this from my terminal", **don't reach for the `dflow` CLI** — it has no discovery subcommands. Write a short HTTP/WS script that hits the Metadata API instead.

## The scanner skeleton

Every scan is the same four steps. Build around this pattern — don't reinvent it per scan:

1. **Enumerate the universe** — `GET /api/v1/markets` (flat) or `GET /api/v1/events?withNestedMarkets=true` (grouped). Filter to `status=active`. Page through until done (see the pagination gotcha for the `{ markets, cursor }` shape). Pass `isInitialized=true` only if the user wants markets tradable on DFlow *right now* (see Gotchas).
2. **Grab the per-market signal.** For top-of-book scans the signal is already on the market object — `yesBid` / `yesAsk` / `noBid` / `noAsk` (4-decimal probability strings), `volume24hFp` / `volumeFp` / `openInterestFp` (dollar-equivalent strings), `closeTime` (unix) — **no orderbook call needed**. For momentum use candlesticks or the `prices` / `trades` WebSocket channels. For ladder depth use `/api/v1/orderbook/by-mint/{mint}`. For recent prints use `/api/v1/trades` or the `trades` channel.
3. **Compute the metric.**
4. **Filter and rank.** Return the top-N (default 10, ask if the user wants more).

### Polling vs streaming

Pick the mode that fits the intent:

- **Polling (REST)** — right when the user wants a snapshot ("show me the top 10 right now", "list all markets with X"). Re-run on a cadence if they want it fresh.
- **Streaming (WebSocket)** — right when the user wants to *act on an event* as it happens ("alert me when YES+NO drops below $1", "flag any market that moves > 5% in a minute", "trade when X trades"). Subscribe to the relevant channel (`prices`, `trades`, `orderbook`) at `wss://<host>/api/v1/ws` and compute the metric on each update. For the full streaming plumbing (reconnection, backoff, subscription lifecycle), hand off to `dflow-kalshi-market-data`.

Exact endpoint params, channel payloads, and pagination → docs MCP.

## Scans to offer

Each scan = a user question + a metric. Plug the metric into the skeleton.

**Prefer rank-based filters over fixed numeric thresholds.** Kalshi volume alone spans 5+ orders of magnitude across active markets — any hardcoded dollar floor is either a pass-through (too low) or excludes everything (too high), and it drifts as the platform grows. When a scan needs "busy" or "cheap" or "moved a lot," compute the cutoff from the scan result (percentile of the current universe), not from a number baked in here.

Only use a fixed number when it's **semantic** — e.g. `YES + NO < $1.00` for arbitrage (that's the no-arb invariant, not a tunable), or `status=active` (a field value, not a threshold). If the user supplies a specific number, use theirs. If the user's phrasing implies a threshold you don't have ("serious volume", "big movers"), ask them — don't guess.

### 1. Arbitrage — `YES + NO < $1`

*"Find markets where I can buy both sides for under a dollar."*
- Metric: `parseFloat(yesAsk) + parseFloat(noAsk) < 1.00`. Semantic threshold — the no-arb invariant; keep this one fixed.
- Rank: largest gap (`1 - sum`) descending.
- Skip rows where either `yesAsk` or `noAsk` is null (no resting ask on that side — not a real arb).

### 2. Long-shot YES

*"Cheap YES that's actually trading."*
- Rank by `parseFloat(volume24hFp)` descending, take the **top quartile of the active universe** as the "actually trading" pool (compute the 75th-percentile cutoff from the scan, don't hardcode a dollar figure).
- Within that pool, sort by `parseFloat(yesAsk)` ascending and return the bottom-N cheapest. If the user supplies a cap ("under 20¢", "under 3¢") use theirs; otherwise rank-only — **don't invent a cents ceiling**. "Cheap" isn't a fixed number; what counts as a long-shot depends on how much the user is willing to tolerate.
- Alternate rank for "best expected payoff": `parseFloat(volume24hFp) / parseFloat(yesAsk)` — busy and cheap at once. Ask the user which they want if ambiguous.
- A cheap market with no volume is a zombie ticker, not a long-shot. Volume-rank first, then look at price — that's the order that filters noise.

### 3. Near-certain short-dated YES

*"YES above 97¢ closing soon — grind the theta."*
- Filter: `parseFloat(yesAsk)` above a user-supplied threshold. "Near-certain" is a phrase, not a number — if the user says 97¢, use 0.97; if they say 99¢, use 0.99. If they just say "near-certain" with no number, ask them what bar they want (95¢? 99¢?). **Don't invent a default cutoff.**
- Rank: `closeTime` ascending — soonest-to-close first.
- Return top-N. If the user specifies a window ("under 48h", "this week"), apply that as an override; don't invent a default window.

### 4. Momentum

*"What moved in the last hour?"* or *"Alert me when something moves"*
- **Polling**: `/api/v1/market/{ticker}/candlesticks` (or `/market/by-mint/{mint}/candlesticks`) per market at the smallest interval, compare latest close vs the close N minutes ago. Per-market and expensive — pre-filter the universe to top-of-volume first (re-use scan #6's ranking, take top-N busy markets, compute momentum on those).
- **Streaming**: subscribe to the `prices` channel (`all: true` or a ticker list) and compute rolling pct change in memory. Much cheaper for the "alert when X happens" variant, and this is how you'd wire "trade when a market moves > N%" (hand the matching market to `dflow-kalshi-trading`).
- Rank by absolute pct change (two-sided) or signed (directional) over a **user-supplied window** — default to 60 minutes if they don't specify, but no default pct threshold. Return top-N. If the user says "moved > N%" they supply N.

### 5. Widest bid-ask spreads

*"Inefficient markets — market-make or avoid."*
- Metric: `parseFloat(yesAsk) - parseFloat(yesBid)` (NO side is symmetric).
- Rank: spread descending.
- Source: market object; no extra calls.

### 6. Highest volume

*"Where's the action?"*
- Metric: `parseFloat(volume24hFp)` (24h dollar-equivalent) or sum over `/api/v1/trades` since a cutoff (intraday). For a live feed, subscribe to the `trades` channel and aggregate in a rolling window.
- Rank: volume descending.

### 7. Closing soonest

*"Theta clock."*
- Metric: `closeTime - now`.
- Rank: ascending.
- Most useful stacked with scan 3 ("near-certain AND closing soon") or scan 6 ("busy AND closing soon").

### 8. Event- and series-level scans

*"Cheapest YES across all outcomes in this event", "do mutually-exclusive buckets sum > 1?"*
- **Within one event** (e.g. "Fed raises rates by X bps" with a bucket per outcome): pull `GET /api/v1/event/{eventTicker}?withNestedMarkets=true`, then reduce across the nested markets (`min(yesAsk)`, `Σ yesAsk`, etc.). Events are the natural scope for single-winner scans.
- **Across a series**: pull `GET /api/v1/series/{seriesTicker}` plus its events, then roll up.
- **There is no `mutuallyExclusive` flag on series or events.** Summing YES across outcomes only makes sense when the outcomes are a partition of one future (one must happen, exactly one can happen). That's a judgment from the event/series title and contract terms — not a field lookup. When in doubt, surface the numbers and flag the assumption to the user.

## Point lookups (N=1)

When the user already has one market in mind, skip the skeleton:
- By ticker: `GET /api/v1/market/{ticker}` (singular `market`, not plural).
- By outcome mint: `GET /api/v1/market/by-mint/{mint}` (slash, not hyphen).
- By event ticker: `GET /api/v1/event/{eventTicker}?withNestedMarkets=true` (singular `event`).
- Free-text: `GET /api/v1/search` (natural-language to events/markets).

The plural forms (`/markets`, `/events`) are the **list** endpoints and take `?cursor=&limit=` for pagination. The singular forms are **point lookups** by id. Mixing them up gets you 404s.

## What to ASK the user (and what NOT to ask)

**Query shape — infer if unambiguous, confirm if not:**

1. **Which scan** (or a plain-English intent you can map to one).
2. **Thresholds the user supplies — use theirs verbatim.** If they say "> 5%" or "under 2¢" or "this week", use those numbers. Otherwise, use the rank-based defaults from each scan above (top quartile by volume, etc.); **do not propose a fixed numeric threshold of your own**. If the user's phrasing implies a threshold the scan doesn't define ("big movers", "serious volume"), ask them — don't guess a number.
3. **Polling vs streaming** — if the intent sounds like "show me now" go REST; if it sounds like "alert me / react when" go WebSocket.
4. **Top-N** (default 10).

**Infra — always ask, never infer:**

5. **DFlow API key** — for the discovery / HTTP portion of the script only; CLI shell-outs authenticate themselves (see the "two auth paths" gotcha below). **Ask with a clean, neutral question: *"For the scanner / discovery side, do you have a DFlow API key?"*** Don't presuppose where the key lives — phrasings like *"do you have it in env?"* or *"is `DFLOW_API_KEY` set?"* nudge the user toward env-var defaults they didn't ask for. Surface the choice; don't silently fall back to env or to dev. It's **one DFlow key everywhere** — same `x-api-key` unlocks the Trade API *and* the Metadata API, REST *and* WebSocket. If yes → prod hosts (`https://prediction-markets-api.dflow.net` REST, `wss://prediction-markets-api.dflow.net/api/v1/ws` WS) with `x-api-key` on every request (REST and the WS upgrade). If no → dev hosts (`https://dev-prediction-markets-api.dflow.net`, `wss://dev-prediction-markets-api.dflow.net/api/v1/ws`), rate-limited; point them at `https://pond.dflow.net/build/api-key` for a prod key. **When you generate a script, log the resolved host + key-presence at startup** (`Using prod Metadata API` / `Using dev Metadata API — rate-limited`) so the user can see which rails they're on without spelunking through code.

From x402agent/solana-clawd, MIT.

More from x402agent/solana-clawd