dflow-kalshi-trading

DFlow Kalshi 取引

Kalshi の予測市場で YES／NO の結果トークンを購入、売却、償還します。PM 取引は非同期です。注文を送信した後、終端状態になるまでポーリングします。

前提条件

• DFlow docs MCP（https://pond.dflow.net/mcp） — リポジトリの README に従ってインストールしてください。このスキルは手順を示し、MCP はリファレンスです。エンドポイントの形式、パラメーターの詳細、エラーコードなど、フィールドレベルの情報は search_d_flow ／ query_docs_filesystem_d_flow で確認してください。推測しないでください。
• dflow CLI（任意。コマンドライン／エージェントで使用する場合） — リポジトリの README に従ってインストールしてください。

使用するインターフェイスを選択する

• CLI — コマンドライン、スクリプト、ローカルエージェント向けです。キーの管理、署名、送信、ポーリングを行います。
• API — ブラウザーウォレット（Phantom、Privy、Turnkey など）を使う Web／モバイルアプリ向けです。ウォレットが署名と RPC を処理します。Trading API は CORS を提供しないため、アプリはバックエンド経由で HTTP リクエストをプロキシする必要があります。

不明な場合は、一度だけ質問してください。「コマンドラインから使いますか、それともアプリに組み込みますか？」

ワークフロー

以下の 3 つのワークフローは、ユーザーがすでにマーケット台帳ミント（CLI の場合。Metadata API の market オブジェクトにある marketLedger フィールド）または結果ミント（API の場合。yesMint ／ noMint）を手元に持っていることを前提としています。ティッカー／イベント名しかない場合は、dflow-kalshi-market-scanner に引き継いでください。

1 つの市場、2 つの決済レール。 DFlow 上で初期化済みの Kalshi 市場はすべて、market.accounts に USDC と CASH の両方のレールを公開します。それぞれに独自の marketLedger、yesMint、noMint があります。注文板は共有されます（最上位の yesBid ／ yesAsk ／ volume24hFp は市場全体の値です）が、取引と保有資産はレールごとに分かれます。USDC レールの YES トークンと CASH レールの YES トークンは別の SPL ミントであり、相互に代替できません。ユーザーが CASH を保有している場合、CASH を明示的に希望している場合、またはアクティブな DFlow ボルトが CASH しか保有していない場合を除き、USDC レールをデフォルトにしてください。「USDC レールがなければ CASH にフォールバックする」という防御的なコードは書かないでください。そのような状況は発生せず、レールの選択をユーザーに知らせないままにしてしまいます。代わりに、スクリプトの冒頭でデフォルトを明示してください。

決済ミントの定数（Solana。CASH は Token-2022、USDC は従来の SPL トークンプログラムを使用）：

• USDC：EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
• CASH：CASHx9KJUStyftLFWGvEVf59SGeG9sh5FfcnZMVPCASH

レールを選択する際は、これらを market.accounts[mint] のキーとして使用してください。/markets のレスポンスには最上位の market.settlementMint フィールドはありません（一部のレシピの断片が market.accounts?.[market.settlementMint] を示唆している場合がありますが、このパターンが登場するのは、保有している結果ミントからレールがすでに判明しているポジション側のコードであり、市場発見コードではありません）。ミントを直接キーにしてください。

購入（YES／NO ポジションの新規取得または増加）

1. このユーザーが購入条件（KYC＋地域制限＋メンテナンス時間帯）を満たしていることを確認します。「注意事項」を参照してください。
2. 決済用ミントを入力（USDC または CASH）に、結果用ミントを出力にして注文を送信します。
3. ステータスが終端状態（closed／expired／failed）になるまでポーリングします。

• CLI：dflow trade <atomic-amount> USDC --market <marketLedger> --side yes|no — 最大120秒間、自動でポーリングします。<FROM> には、base58 ミントまたは省略形の USDC／CASH を指定できます（CLI は現物取引と同様、限られたシンボルを解決します）。--market には、<from> 引数に一致する決済トラックの marketLedger を指定します。つまり、Metadata API のレスポンスにある market.accounts[<USDC-or-CASH-mint>].marketLedger です。CLI は --side と <from> から YES／NO の結果用ミントを導出するため、--side yes と --side no のどちらでも同じ marketLedger の値を使用します。ここで yesMint／noMint を渡さないでください。これらは CLI ではなく API の入力値です。ドキュメント内の「market mint」と「market ledger mint」という表現は、どちらもこの同じフィールドを指します。

スナップショットの価格から「契約をN個購入」する場合。 Kalshi の購入注文では USDC 額を送信し、その金額で購入できる分の契約を整数個受け取り、余りは返金されます。スナップショットの yesAsk をもとに N 個の契約を執行する場合は、Math.ceil(N * yesAsk * 1e6) アトミック USDC を計算します。必要に応じて少額のバッファー（約1％以下。通常は数ベーシスポイントで十分）を加えると、スキャンから注文送信までの間に売り気配値が上昇して、N−1 個しか買えなくなるのを防げます。余ったステーブルコインは CLP によって返金されるため、少し多めに資金を入れるのは安価な保険です。ただし、1～2％を超えて多く入れないでください。それ以上は保険ではなく、注文サイズが変わってしまいます。

• API：GET /order?userPublicKey=&inputMint=<settlement>&outputMint=<yesMint|noMint>&amount=<atomic> を呼び出し、署名して送信した後、/order-status をポーリングします。API には結果用ミントを直接渡します（--market による間接指定はありません）。フィールドの詳細は docs MCP で確認できます。

売却（ポジションの縮小または決済）

ミントを入れ替え、結果用ミントを入力、決済用ミントを出力にします。KYC は不要です。 CLI では --market／--side を指定せず、FROM の位置引数に結果用ミントを渡します。CLI が決済用ミントを自動で解決します。

• CLI：dflow trade <atomic-outcome> <outcome-mint>
• API：購入時と同じ /order 呼び出しを使い、入力ミントと出力ミントを入れ替えます。

償還（決済後）

市場が determined／finalized となり、かつ redemptionStatus: "open" になったら、勝ち側のポジションを決済用ミントに売却するだけで償還できます。特別なフラグも KYC も不要です。

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

取引の内容 — 明確に推測できる場合は推測し、不明確な場合は確認します。

1. 操作 — 購入／売却／償還。意図から推測します（「Xに賭けたい」→ YESを購入、「現金化したい」→ 売却、「自分のYESトークンが勝った」→ 償還）。ユーザーにモードを選ばせないでください。
2. 市場とサイド — CLI の場合：marketLedger（market.accounts[<settlement-mint>].marketLedger から取得）と --side yes|no。API の場合：YES または NO の結果用ミントを outputMint に直接指定します。
3. 決済レール — USDC または CASH。初期化済みのすべての市場で両方を利用できます。ユーザーから別の指定がなければ USDC をデフォルトにします。これにより、使用する marketLedger（CLI）または yesMint／noMint（API）が決まります。
4. アトミック単位での数量 — Kalshi のミントはすべて小数点以下6桁です（8_000_000 = USDC 8ドル、10_000_000 = 結果トークン10個）。購入では決済用ミントの数量（USDC／CASH）を送信し、売却／償還では結果トークンの数量を送信します。

インフラ — 必ず尋ね、推測しないでください： 5. API のみ — ウォレットの公開鍵（base58）。すべての /order 呼び出しで必須です。 6. API のみ — DFlow API キー（スクリプトが /order またはその他の Trade API エンドポイントに直接 HTTP リクエストを送信する場合のみ必要です。CLI のみを使うスクリプトには不要です。「2 つの認証方法」の注意点を参照してください）。中立で簡潔な質問をしてください：「DFlow API キーをお持ちですか？」 キーの保管場所を決めつけないでください。「環境変数にありますか？」 や 「DFLOW_API_KEY は設定されていますか？」 といった聞き方は、ユーザーが求めていない環境変数の使用を促してしまいます。選択肢を提示し、環境変数や dev へのフォールバックを黙って行わないでください。DFlow のすべての機能で同じキーを使います。同じ x-api-key で Trade API と Metadata API の両方、REST と WebSocket の両方を利用できます。キーを持っている場合 → 本番ホスト https://quote-api.dflow.net を使い、すべてのリクエストに x-api-key を付けます。持っていない場合 → dev ホスト https://dev-quote-api.dflow.net を使います（機能は同じですが、レート制限があります）。本番キーの取得先として https://pond.dflow.net/get-started/api-key を案内してください。独自に HTTP リクエストを送信するスクリプトを生成する場合は、起動時に解決されたホストとキーの有無をログに記録し、ユーザーがどの接続先を使っているか確認できるようにしてください。 7. 優先手数料（どちらの利用方法でも） — 「優先手数料の希望はありますか？ それとも DFlow のデフォルトを使いますか？」どちらの利用方法でもデフォルトは DFlow の自動設定で、上限は 0.005 SOL です（/order に記載されたデフォルト値）。混雑時やコスト重視のワークフローで調整できることをユーザーが把握できるよう、この設定について明示してください。どの割合の取引が対象になるかについて意見を述べないでください。DFlow はその割合を公表しておらず、こちらにも分からないためです。

• API — /order に prioritizationFeeLamports を渡します。値は auto、medium、high、veryHigh、disabled、または lamports 単位の整数です。調整用のリアルタイム推定値は GET /priority-fees（スナップショット）と /priority-fees/stream（WebSocket）で取得できます。
• CLI — 調整用フラグはありません。dflow trade は常にサーバー側のデフォルトを使用します。より細かく制御する必要がある場合（正確な lamports 値の指定、または disabled の指定）は、API を使う必要があります。

8. スポンサー負担／ガスレス（API のみ。CLI では省略） — 「この取引ではユーザーが SOL を保有している必要がありますか？ それともアプリが手数料を負担しますか？」デフォルトではすべてユーザーが支払います。負担する範囲に応じて、/order で次の 2 つの方法を使えます。
   • sponsor=<sponsor-wallet-base58> — スポンサーがトランザクション手数料、ATA の作成費用、市場初期化費用を負担します。トランザクションにはユーザーとスポンサーの両方の共同署名が必要です。任意の sponsorExec=true|false で、スポンサーが実行する（デフォルト）かユーザーが実行するかを選択できます。
   • predictionMarketInitPayer=<wallet> — 1 回限りの市場初期化にかかる rent のみを負担します。ユーザーは引き続き署名し、自身のトランザクション手数料と ATA の作成費用を支払います。初期化費用のみを負担したい場合に便利です。GET /prediction-market-init を使って、事前に別途市場を初期化することもできます。
   • CLI は、どちらのスポンサー設定にも対応していません。

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

• RPC — CLI ユーザーは dflow setup 中に設定します。ブラウザーウォレットを使う API ユーザーは、自分の RPC を用意する必要はありません（ウォレットが処理します）。サーバー側で署名する場合のみ尋ねてください。必要な場合は Helius を提案してください。
• スリッページ — どちらの利用方法でもデフォルトは "auto" で、CLP から取得する約定に適しています。上書きするのは、ユーザーから明示的な依頼があった場合のみです（CLI は --slippage、API は predictionMarketSlippageBps）。
• プラットフォーム手数料 — ユーザーがそちらに話題を移した場合は、dflow-platform-fees に案内してください。

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

• Kalshi のすべての mint は 6 桁の小数精度です。 USDC、CASH、すべてのアウトカムトークンが対象です。API には必ず最小単位で指定してください。
• 買い注文は契約単位のみです。端数の契約は購入できません。 USDC/CASH の金額を送信すると、その金額で購入できる整数個の契約をシステムが購入し、残ったステーブルコインは返金します。注文の最低金額は 0.01 USDC ですが、実際の最低金額は市場ごとの現在の YES/NO 価格における契約 1 件分です（例：YES が 0.43 で取引されている場合、最小単位で 430_000 以上＝$0.43 が必要です）。ユーザーの金額が最低金額に近い場合は、まず見積もりを取得してください。
• 約定は例外なく非同期です。 PM /order は executionMode: "async" を返します。トランザクションがオンチェーンに記録されても、約定したことにはなりません。注文は CLP で期限切れまたは失敗になる可能性があります。必ず /order-status をポーリングし、終端状態になるまで確認してください。CLI は 120 秒間自動でポーリングします。タイムアウトした場合は、dflow status <orderAddress> --poll で確認を続けてください。
• 購入にはゲートがあります。呼び出しごとではなく、セッションごとに一度確認してください。
  • Proof KYC — 購入には必須ですが、売却と償還には不要です。セッション開始時に一度、GET https://proof.dflow.net/verify/{address}（公開、認証不要）を呼び出し、{ verified: boolean } をキャッシュして、購入 UI の表示をそのキャッシュに基づいて制御してください。/order の判定が最終的なものです。まれに検証に失敗した場合は、details.deepLink を使って unverified_wallet_not_allowed（API）／PROOF_NOT_VERIFIED（CLI）にフォールバックしてください。
  • ジオブロック — 一部の管轄区域では制限されています。API ビルダーは独自の UI で適用し（ユーザーの国をセッションごとに一度キャッシュします）、CLI は内部で処理して category: "geoblock" を返します。ポリシー：https://pond.dflow.net/legal/prediction-market-compliance。
• メンテナンス時間。 Kalshi は毎週 木曜日の午前 3:00～5:00（ET） にオフラインになります。CLP はルートの提供を停止し、/order は route_not_found を返します（CLI はメンテナンスに関する注記を付加します）。この時間帯は PM 注文の送信を停止してください。
• route_not_found は包括的なエラーです。 mint の誤り、契約価格の最低金額に満たない金額、現時点で流動性がない場合、または メンテナンス時間帯を意味します。流動性不足と判断する前に、mint、最小単位で指定された金額、その金額で契約を 1 件以上購入できることを確認してください。
• ブラウザーアプリではプロキシが必要です。 Trading API は CORS に対応していません。バックエンド（Next.js API ルートなど）から呼び出し、ブラウザーから直接呼び出さないでください。
• CLI のシェル呼び出しは独自に認証しますが、HTTP の直接呼び出しは認証しません。 スクリプトやバックエンドから dflow trade をシェル呼び出しすると、その処理では dflow setup で CLI に保存された設定（キー、ウォレット、RPC）が使われます。CLI 呼び出しのためにこちらで設定を渡す必要はありません。同じスクリプトで Trade API や Metadata API を HTTP で直接呼び出す場合（例：スキャナー形式の検出、独自の /order 呼び出し、/quote、関連する HTTP ツールなど）は、その HTTP クライアントにキーを明示的に渡す必要があります（環境変数、.env、--api-key フラグ、ヘッダーなど）。CLI に保存されたキーを関連する HTTP クライアントで再利用することはできず、環境変数のキーも CLI には渡されません。同じ DFlow キーでも、それぞれ独立して設定する必要があります。HTTP 部分でのみ API キーを確認してください。CLI だけを使うスクリプトには不要です。

該当しない場合

上記に記載のない内容（すべてのパラメーター一覧、すべてのエラーテーブル、レスポンススキーマ、一部約定の処理、まれに使うフラグ、新機能など）については、docs MCP（search_d_flow、query_docs_filesystem_d_flow）で調べてください。推測で答えないでください。

実行可能なコードについては、DFlow docs recipes をユーザーに案内してください（各レシピから、すぐにクローンして使える DFlow Cookbook Repo にリンクしています）：/prediction-markets/recipes/increase-position、/prediction-markets/recipes/decrease-position、/prediction-markets/recipes/redeem-outcome-tokens。

関連スキル

ユーザーが次の話題に移った場合は、該当するスキルに引き継ぎます。

• dflow-kalshi-market-scanner — 市場を検索し、イベントやカテゴリーで絞り込みます
• dflow-kalshi-market-data — リアルタイム価格、オーダーブック、ストリームを確認します
• dflow-kalshi-portfolio — ポジションと未実現損益を確認します
• dflow-proof-kyc — ウォレットでProof認証を設定します
• dflow-platform-fees — PM取引でビルダー手数料を請求します
• dflow-spot-trading — Kalshi以外のトークンスワップ