dflow-kalshi-trading

DFlow Kalshi 交易

在 Kalshi 预测市场买入、卖出和兑换 YES/NO 结果代币。PM 交易是异步的——提交后轮询，直到进入终态。

前提条件

• DFlow 文档 MCP（https://pond.dflow.net/mcp）——按照仓库 README 安装。此技能提供操作步骤；MCP 提供参考资料。使用 search_d_flow / query_docs_filesystem_d_flow 查询端点结构、参数详情、错误代码及其他字段级信息——不要猜测。
• dflow CLI（可选，用于命令行/Agent）——按照仓库 README 安装。

选择使用方式

• CLI——命令行、脚本、本地 Agent。负责管理密钥、签名、提交和轮询。
• API——配合浏览器钱包（Phantom、Privy、Turnkey 等）使用的 Web/移动应用。钱包负责签名和 RPC；应用必须通过自己的后端转发 HTTP 请求（Trading API 不提供 CORS）。

如果不清楚，请询问一次：“通过命令行使用，还是集成到应用中？”

工作流

以下三种工作流都假设用户已经持有 market ledger mint（CLI；Metadata API 市场对象中的 marketLedger 字段）或 outcome mint（API；yesMint / noMint）。如果用户只有代码 / 事件名称，请转到 dflow-kalshi-market-scanner。

一个市场，两种结算通道。 DFlow 上每个已初始化的 Kalshi 市场都会在 market.accounts 中同时提供 USDC 和 CASH 通道——每个通道都有自己的 marketLedger、yesMint 和 noMint。它们共用一个订单簿（顶层的 yesBid / yesAsk / volume24hFp 是市场级数据），但交易和持仓按通道区分：USDC 通道的 YES 代币与 CASH 通道的 YES 代币使用不同的 SPL mint，不能互换。默认使用 USDC 通道，除非用户持有 CASH、明确要求使用 CASH，或当前 DFlow 金库只有 CASH。不要编写“如果找不到 USDC 通道就回退到 CASH”的防御性代码——这种情况永远不会发生，而且会对用户隐藏通道选择。应在脚本开头说明默认选择。

结算 mint 常量（Solana 上，CASH 使用 Token-2022，USDC 使用经典 SPL 代币程序）：

• USDC：EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
• CASH：CASHx9KJUStyftLFWGvEVf59SGeG9sh5FfcnZMVPCASH

选择通道时，将这些值用作 market.accounts[mint] 的键。/markets 响应中没有顶层的 market.settlementMint 字段（尽管某些操作示例可能会使用 market.accounts?.[market.settlementMint]——这种模式出现在持仓侧代码中，因为该代码已根据持有的结果 mint 知道通道，而非出现在市场发现代码中）。直接按 mint 查找。

买入（开立或增加 YES/NO 仓位）

1. 确认该用户满足买入门槛（KYC + 地理位置 + 维护时段）——请参阅注意事项。
2. 提交订单时，将结算铸币地址作为输入（USDC 或 CASH），将结果铸币地址作为输出。
3. 轮询状态，直到进入终态（closed / expired / failed）。

• CLI：dflow trade <atomic-amount> USDC --market <marketLedger> --side yes|no — 自动轮询，最长 120s。<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——这些是 API 接口的输入参数，不适用于 CLI。文档中提到的“market mint”和“market ledger mint”都指这个字段。

根据扫描快照“买入 N 份完整合约”。 Kalshi 买入订单以 USDC 金额提交，并按该金额可覆盖的数量买入完整合约，剩余款项会退还。根据快照中的 yesAsk 执行 N 份合约时，计算 Math.ceil(N * yesAsk * 1e6) 个原子单位的 USDC；也可以选择额外增加少量缓冲（≤ 约 1%，几个基点通常就足够），避免扫描与提交之间卖价上涨而导致最终只买到 N-1 份。CLP 会退还剩余稳定币，因此略微多付是成本很低的保险。不要多付超过百分之一或两个百分点——超过这个程度就不再是保险，而是在下不同金额的订单。

• API：GET /order?userPublicKey=&inputMint=<settlement>&outputMint=<yesMint|noMint>&amount=<atomic>，然后签名、提交并轮询 /order-status。API 直接接受结果铸币地址（不需要通过 --market 间接指定）。字段详情请参阅文档 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 = 8 美元 USDC；10_000_000 = 10 个结果代币）。买入提交结算铸币地址金额（USDC/CASH）；卖出/赎回提交结果代币数量。

基础设施——始终询问，不要推断： 5. 仅限 API — 钱包公钥（base58）。每次调用 /order 都必填。 6. 仅限 API — DFlow API 密钥（仅当脚本直接调用 /order 或其他 Trade API 端点时需要；纯 CLI 脚本不需要——参见“两个认证路径”注意事项）。请用简洁、中性的方式询问：“你有 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 始终使用服务端默认值。如果用户需要更精细的控制（精确的 lamport 值或 disabled），则必须改用 API。

8. 赞助 / 免 Gas（仅限 API——CLI 跳过）——“这笔交易需要用户持有 SOL 吗，还是由你的应用承担费用？”默认由用户支付所有费用。/order 提供两个选项，具体取决于你想承担哪些费用：
   • sponsor=<sponsor-wallet-base58>——赞助方支付交易费用、ATA 创建费用和市场初始化费用。交易必须由用户和赞助方共同签名。可选的 sponsorExec=true|false 用于选择由赞助方执行（默认）还是由用户执行。
   • predictionMarketInitPayer=<wallet>——仅承担一次性市场初始化租金；用户仍需自行签名，并支付自己的交易费用和 ATA 创建费用。适用于只想承担初始化费用的情况。也可以通过 GET /prediction-market-init 预先在链下初始化市场。
   • CLI 不支持这两种赞助方式。

不要询问以下内容：

• RPC——CLI 用户会在 dflow setup 时设置。使用浏览器钱包的 API 用户不需要自己的 RPC（由钱包处理）。只有在服务端签名时才需要询问。如果需要，请推荐 Helius。
• 滑点——两种方式的默认值都是 "auto"，适用于 CLP 来源的成交。仅在用户明确提出要求时才覆盖（CLI 使用 --slippage；API 使用 predictionMarketSlippageBps）。
• 平台费用——如果用户转而讨论平台费用，请交由 dflow-platform-fees 处理。

注意事项（文档 MCP 不会主动告诉你的内容）

• 所有 Kalshi 铸造的代币都是 6 位小数。 USDC、CASH 和所有结果代币都是如此。始终向 API 传入原子单位。
• 买入只能按整份合约进行，不能买入合约的零头。 提交 USDC/CASH 金额；系统会按该金额所能覆盖的数量买入整份合约，并退还剩余的稳定币。每笔订单的最低金额为 0.01 USDC，但在任何具体市场中，实际最低金额是一份合约的当前 YES/NO 价格（例如，若 YES 的交易价格为 0.43，则至少需要 430_000 个原子单位，即 $0.43）。如果用户的金额接近最低门槛，请先查询报价。
• 成交是异步的，没有例外。 PM /order 会返回 executionMode: "async"。交易上链并不代表订单已成交——订单仍可能在 CLP 中过期或失败。始终轮询 /order-status，直至订单进入终态。CLI 会自动轮询 120s；若超时，请继续执行 dflow status <orderAddress> --poll。
• 存在买入门槛；每个会话检查一次，不要每次调用都检查。
  • Proof KYC — 买入需要通过验证（卖出和赎回不需要）。在会话开始时调用一次 GET https://proof.dflow.net/verify/{address}（公开接口，无需身份验证），缓存 { verified: boolean }，并根据缓存控制买入界面。/order 仍是最终依据；若罕见情况下验证未通过，则使用 details.deepLink 处理 unverified_wallet_not_allowed（API）/ PROOF_NOT_VERIFIED（CLI）。
  • 地理封锁 — 某些司法管辖区会受到限制。API 构建者应在自己的界面中执行限制（每个会话缓存一次用户所在国家/地区）。CLI 会在内部处理，并返回 category: "geoblock"。政策：https://pond.dflow.net/legal/prediction-market-compliance。
• 维护时段。 Kalshi 每周四 美国东部时间凌晨 3:00–5:00 离线。CLP 会停止提供路由；/order 会返回 route_not_found（CLI 会附加维护提示）。整个时段都应禁止提交 PM 订单。
• route_not_found 是一个兜底错误。 可能是铸造地址错误、金额低于合约价格门槛、当前流动性不足，也可能是处于维护时段。认定流动性不足之前，请先确认铸造地址和原子单位正确，并确保金额至少能买入 ≥ 1 份合约。
• 浏览器应用必须使用代理。 Trading API 不提供 CORS——应从后端调用（例如 Next.js API 路由或同类方案），绝不要直接从浏览器调用。
• 通过 shell 调用 CLI 会自行进行身份验证；直接 HTTP 调用则不会。 如果脚本或后端通过 shell 调用 dflow trade，该调用会使用 dflow setup 中保存的 CLI 配置（密钥、钱包、RPC）——调用 CLI 时无需自行传入任何内容。如果同一个脚本还通过 HTTP 直接访问 Trade API 或 Metadata API（例如扫描器式发现、自行调用 /order、/quote 或其他 HTTP 工具），则必须明确向该 HTTP 客户端传入密钥（环境变量、.env、--api-key 标志或请求头）。CLI 保存的密钥不能由其他 HTTP 客户端复用，环境变量中的密钥也不会注入 CLI——它们是使用同一个 DFlow 密钥的两个独立配置位置。只有 HTTP 部分需要询问 API 密钥；纯 CLI 脚本不需要。

遇到不适用的情况时

对于上文未涵盖的内容——完整参数列表、完整错误表、响应架构、部分成交处理、少见标志或新功能——请查询文档 MCP（search_d_flow、query_docs_filesystem_d_flow）。不要猜测。

如需可运行的代码，请引导用户查看 DFlow 文档中的配方（每个配方都链接到 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 代币兑换