dflow-kalshi-market-data

DFlow Kalshi マーケットデータ

既知の Kalshi マーケット（または複数のマーケット）に関するデータを、スナップショット、過去の期間、ライブストリームとして取得します。データには、オーダーブック、取引、価格、ローソク足、予測、ゲーム中のライブデータが含まれます。

前提条件

• DFlow docs MCP（https://pond.dflow.net/mcp）— リポジトリの README に従ってインストールしてください。このスキルは手順書であり、MCP がリファレンスです。クエリパラメーター、ページネーション、正確なペイロードスキーマ、WebSocket のスナップショットと差分のセマンティクス、カテゴリ固有の live_data.details の形式はすべて MCP に記載されています。推測しないでください。

インターフェース

このスキルのすべてのデータエンドポイントは、Metadata API（https://pond.dflow.net/resources/metadata-api）を使用します。スナップショットと履歴には REST、ライブストリームには WebSocket を使います。コマンドラインからの curl、Node／Python スクリプト、cron ジョブ、バックエンド、ブラウザー UI の前段に置く Next.js プロキシなど、どこからでも呼び出せます。

ユーザーが「これを自分のターミナルから実行して」と言った場合、dflow CLI を使わないでください。市場データ用のサブコマンドはありません。代わりに Metadata API を使う簡潔な HTTP／WS スクリプトを作成してください。

まずデータの形を選ぶ

3 つの目的に、3 つの形があります。ユーザーの表現に合わせて、エンドポイントを選んでください。

• スナップショット（「今すぐ」「現在」）→ REST、1 回の呼び出し。
• 履歴（「過去 1 時間」「T1 と T2 の間」「直近 N 件の取引」）→ 時刻／上限パラメーターを指定した REST。
• ストリーム（「ライブ」「発生したらすぐ」「発生したら通知して」）→ WebSocket サブスクリプション。

データ → エンドポイント対応表

以下の各データセットについて、各行の説明で 3 つの形すべてを網羅しています。フィールド単位の詳細（正確なパラメーター、ページネーショントークン、ペイロードスキーマ）については、docs MCP を参照してください。

オーダーブック

• スナップショット：GET /api/v1/orderbook/{ticker} または /api/v1/orderbook/by-mint/{mint}（sequence を含みます）。
• ストリーム：orderbook チャネル（更新ごとの yes_bids と no_bids のマップ。ストリームのペイロードには sequence がありません）。

取引 — スコープが一部重複する、異なる 2 つのエンドポイント

• GET /api/v1/trades（および /trades/by-mint/{mint}）— 市場の完全な約定履歴。Kalshi のオーダーブックで約定したすべての取引が対象です。DFlow のオンチェーン約定も含まれます（これらも Kalshi のオーダーブックで約定します。「Do onchain trades show up on Kalshi's trade websocket?」FAQ を参照）。「この市場の取引を見せて」のデフォルトはこちらです。ストリームに相当するのは trades チャネルです。
• GET /api/v1/onchain-trades（および /onchain-trades/by-market/{ticker}、/onchain-trades/by-event/{eventTicker}）— DFlow のオンチェーン約定のみを取得します。/trades には含まれない、オンチェーン固有のフィールドである wallet、transactionSignature、id、inputAmount、outputAmount、createdAt を含みます。/trades に含まれるデータの一部ですが、行ごとの情報はより豊富です。WS ストリームはありません。
• 選び方：完全な約定履歴 → /trades。ウォレット単位のアクティビティフィード、DFlow の執行分析、トランザクション署名の検索 → /onchain-trades。特定のユーザー注文の約定をリアルタイムで検出する場合は、プログラムイベントを直接解析してください（/prediction-markets/onchain-trade-parsing を参照）。

最良気配値

• スナップショット：マーケットオブジェクトから yesBid／yesAsk／noBid／noAsk を直接読み取ります（GET /api/v1/market/{ticker} — 単数形）。個別のエンドポイントはありません。
• ストリーム：prices チャネル。

ローソク足（OHLCV）

• マーケット単位：GET /api/v1/market/{ticker}/candlesticks または /api/v1/market/by-mint/{mint}/candlesticks。
• イベント単位：GET /api/v1/event/{ticker}/candlesticks。
• リクエストごとに最大 5,000 本（「注意点」を参照）。

予測パーセンタイルの履歴

• イベント単位：GET /api/v1/event/{seriesTicker}/{eventId}/forecast_percentile_history（および /api/v1/event/by-mint/{mint}/forecast_percentile_history）。あるイベントについて、Kalshi の過去の予測分布を取得します。

ライブデータ（Kalshi パススルー）

• GET /api/v1/live_data、/live_data/by-event/{ticker}、/live_data/by-mint/{mint}。
• レスポンスには details オブジェクトが含まれます。フィールドはマイルストーンの種類によって異なります。フットボール、サッカー、テニス、ゴルフ、MMA、野球、クリケット、競馬には、それぞれ固有の既知フィールドセットがあります。details を扱う前に、ドキュメント MCP の live-data-details を参照してください。

ストリーミングのライフサイクル

接続 → 購読 → 処理 → 再接続。それぞれ一文で説明します。

• 接続：開発環境では wss://dev-prediction-markets-api.dflow.net/api/v1/ws（認証不要）を使用します。本番環境では wss://prediction-markets-api.dflow.net/api/v1/ws を使用し、WS アップグレードヘッダーに x-api-key を設定します。REST の場合は、それぞれ https://dev-prediction-markets-api.dflow.net と https://prediction-markets-api.dflow.net を使用します。
• 購読：{ type: "subscribe", channel: "prices" | "trades" | "orderbook", all: true | tickers: [...] } を送信します。各チャンネルは独立した購読状態を持ちます。
• 処理：各メッセージを channel に基づいて解析し、非同期で処理します。読み取りループをブロックしないでください。
• 再接続：切断時は指数バックオフで再接続し、再接続後にすべての購読を再送信します。サーバーは購読状態を記憶しません。

正確なメッセージスキーマ（prices、trades、orderbook）、ハートビート／ping の動作、orderbook チャンネルにおける差分とスナップショットの意味 → ドキュメント MCP。

ユーザーに尋ねること（尋ねてはいけないこと）

クエリの内容 — 一意に判断できる場合は推測し、判断できない場合は確認します：

1. どの市場か — ティッカーまたは結果ミント。
2. どのデータセットか — orderbook、trades（Kalshi とオンチェーンのどちらか）、prices、candles、forecasts、または live data。
3. スナップショット／履歴／ストリームのどれか — 言い回しから推測し、曖昧な場合は確認します。
4. 履歴の範囲／間隔 — 時間範囲（startTs、endTs）と candles の periodInterval、trades の limit。

インフラ — 必ず尋ね、推測しないでください：

5. DFlow API キー。 簡潔で中立的な質問をしてください：「DFlow API キーをお持ちですか？」 キーがどこにあるかを決めつけないでください。*「環境変数にありますか？」や「DFLOW_API_KEY は設定されていますか？」*といった聞き方は、ユーザーが求めていない環境変数の使用を促してしまいます。ユーザーが dflow CLI を設定済みだと言っただけで、API キーも持っていると決めつけてはいけません。選択肢を提示し、環境変数や開発環境へ黙ってフォールバックしないでください。DFlow のすべての機能で同じキーを使います。同じ x-api-key で Trade API と Metadata API の両方、REST と WebSocket の両方を利用できます。キーがある場合 → 本番ホスト（REST は https://prediction-markets-api.dflow.net、WS は wss://prediction-markets-api.dflow.net/api/v1/ws）を使用し、すべてのリクエスト（REST と WS アップグレード）に x-api-key を設定します。ない場合 → レート制限のある開発ホスト（https://dev-prediction-markets-api.dflow.net、wss://dev-prediction-markets-api.dflow.net/api/v1/ws）を使用し、本番キーの取得先として https://pond.dflow.net/get-started/api-key を案内します。スクリプトを生成する場合は、起動時に解決したホストとキーの有無をログに出力し、ユーザーがどの接続先を使っているか確認できるようにしてください。

次のことは尋ねないでください：

• RPC、ウォレット、署名 — このスキルは読み取り専用の公開データを扱います。
• 決済ミント／スリッページ／手数料 — 取引側の事項です。ここで見た情報をもとにユーザーが注文を出そうとした場合は、dflow-kalshi-trading に引き継いでください。

注意点（docs MCP からは自発的に教えてくれないこと）

• 取引エンドポイントは2つあり、対象範囲が重複しています。 /api/v1/trades は市場全体の取引履歴です（Kalshi のオフチェーン注文フロー および DFlow のオンチェーン約定。DFlow の約定は Kalshi の板に反映されます）。/api/v1/onchain-trades は DFlow のオンチェーン取引のサブセットで、wallet ／ transactionSignature ／ 入出力量が追加されています。ユーザーが「この市場の取引を表示して」と言ったら /trades を使い、「このウォレットの DFlow アクティビティを表示して」と言ったら /onchain-trades?wallet=... を使います。
• オーダーブックが返すのはビッドの段階的な価格一覧のみです（yes_bids、no_bids）。最良の YES アスク は 1 - max(no_bids keys) から導出します（価格 p の NO ビッドは、価格 1-p の YES オファーです）。REST と WS チャネルの両方で同じです。
• 価格スケールが2種類あります。 オーダーブックと prices チャネルでは確率を表す文字列（"0.4200"）が使われます。/trades と trades チャネルでは 0～10000 の整数が使われ、yes_price_dollars ／ no_price_dollars の文字列が併記されます。計算する前に正規化してください。
• リクエストあたりのローソク足上限は5,000本で、超えると必ず 400 が返されます。 範囲と間隔から算出されるローソク足が5,000本を超える場合、エンドポイントは 部分的な結果を返さずに 400 を返します。これは DFlow 経由で転送される Kalshi 側の上限です。範囲を狭める、間隔を広げる、または自分でページングしてください。
• periodInterval の単位は秒ではなく分です。 Kalshi の慣例では、1 は1分足、60 は時間足、1440 は日足です。秒単位だと思い込むと、5,000本の上限を簡単に超えてしまいます。
• live_data.details は汎用的なフィールドではなく、カテゴリ別のフィールドです。 フィールドはマイルストーンの種類ごとに異なります。複数のカテゴリに共通するフィールドとしてアクセスするコードをハードコードしないでください。type に応じて分岐し、MCP の live-data-details リファレンスから該当カテゴリの既知のフィールドを取得してください。
• WebSocket の all: true は大量のデータを垂れ流します。 特に prices と orderbook では注意してください。全市場を監視する必要が本当にある場合を除き、ティッカーのリストを使ってください。
• WS のサブスクリプションは再接続後に維持されません。 接続が切れた後に再接続するたび、切断前に送信していた subscribe メッセージをすべて再送してください。
• メンテナンス時間帯はストリームが途切れることがあります — 木曜日の午前3:00～5:00（ET）は Kalshi がオフラインになります。WS トラフィックがまばらになったり、欠落したり、REST フィールドが古くなったりすることを想定してください。
• CLI に保存したキーは、スクリプトの HTTP クライアントには引き継がれません。 dflow setup で保存したキーは、dflow バイナリ自体が使うものです。スクリプトから直接呼び出す Metadata API には別途キーが必要です（環境変数、.env、フラグなどで渡してください）。DFlow キー自体は1つですが、同じコードベースで CLI の呼び出しと HTTP ／ WS の直接呼び出しを混在させる場合、キーを設定する箇所は2つあります。

想定どおりにいかない場合

上記で扱っていない内容（全パラメーターの一覧、ページネーショントークン、WS メッセージの正確な形式（オーダーブックのスナップショットと差分、ハートビートの頻度）、ローソク足の間隔の列挙値、カテゴリ別の live_data.details フィールド、予測パーセンタイルのレスポンス形式など）については、docs MCP（search_d_flow、query_docs_filesystem_d_flow）に問い合わせてください。推測しないでください。

関連スキル

• dflow-kalshi-market-scanner — 条件に合う市場を全体から検索します（このプリミティブを使い、名前付きスキャンとして整形します）。
• dflow-kalshi-trading — ここで監視している市場で、買い注文／売り注文／償還注文を出します。
• dflow-kalshi-portfolio — ユーザー自身のポジションと損益を表示します。