dflow-spot-trading

DFlow 现货交易

通过 DFlow 交换任意一对 Solana 代币。交易是同步的：一次 /order 调用会返回一笔可供签名的交易，你只需签名、提交并确认。

前提条件

• DFlow docs MCP（https://pond.dflow.net/mcp）：按照仓库 README 安装。本技能提供操作方案；MCP 是参考资料。请在其中查找端点结构、参数详情和错误代码，不要自行猜测。
  • 约定：本技能中未加限定的文档路径（例如 /resources/trading-api/order/order）是 MCP 路径。使用 query_docs_filesystem_d_flow（对 .mdx 文件使用 cat/head）或 search_d_flow 阅读，不要通过浏览器抓取。完整的 https:// 链接是面向用户的目标地址（可运行的操作方案、API 密钥注册页面），应提供给用户。
• dflow CLI（可选，用于命令行/Agent）：按照仓库 README 安装。

选择使用方式

• CLI：适用于命令行、脚本和本地 Agent。负责管理密钥、签名和广播。
• API：适用于 Web/移动应用、后端，以及使用自有签名器的自动化流程。浏览器应用必须通过后端代理 HTTP 请求（Trading API 不提供 CORS）。

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

工作流

报价（只读）

• CLI：dflow quote <atomic-amount> <FROM> <TO>
• API：GET /order 也可用于获取报价。不传 userPublicKey 调用时，会返回价格字段，不附带交易；这正是用户连接钱包之前获取报价所需的方式。/quote 仍然可用，但新集成优先使用 /order。（报价/响应字段列表：通过 docs MCP 加载 /resources/trading-api/order/order。）

交易（/order）

一次调用即可获取报价和可供签名的交易，然后签名、提交并确认。支持所有 SPL 和 Token-2022 铸币。

完整的请求/响应架构、所有参数和错误代码：通过 docs MCP 加载 /resources/trading-api/order/order（query_docs_filesystem_d_flow）。

• CLI：dflow trade <atomic-amount> <FROM> <TO>（对于需要阻塞等待确认的 Agent/脚本，请添加 --confirm）。
• API：GET /order?userPublicKey=&inputMint=&outputMint=&amount=&transactionVersion=v1，解码 base64 格式的 transaction，对其签名，通过你的 RPC 提交并确认。构建、签名和发送交易需要 @solana/kit（>=8.0.0）。DFlow 快速入门模式：

const params = new URLSearchParams({
  userPublicKey, inputMint, outputMint, amount,
  transactionVersion: "v1",
});
const { transaction } = await fetch(`/api/order?${params}`).then(r => r.json());

const tx = getTransactionDecoder().decode(getBase64Encoder().encode(transaction));
const signed = await signTransaction([keypair], tx);
const wireTx = getBase64EncodedWireTransaction(signed);

const sig = await rpc.sendTransaction(wireTx, { encoding: "base64" }).send();
// Poll getSignatureStatuses (or your framework's confirm helper) before treating the trade as landed.

/order 响应字段的用途（权威值由 DFlow 提供，因此应直接展示这些值，而不是重新计算）：

• transaction（base64）：解码、签名并提交。
• inAmount / outAmount / otherAmountThreshold / priceImpactPct / slippageBps：展示。
• prioritizationFeeLamports / prioritizationType："auto" 解析后由服务端确定的优先费用选项；回传或记录。
• contextSlot：用于日志记录/过期检查。
• routePlan：可选展示/调试。

架构中标记为 “当且仅当请求包含用户公钥时才指定” 的字段（transaction、lastValidBlockHeight、computeUnitLimit、prioritizationFeeLamports）在仅获取报价的调用中不存在，因此使用前请先检查。

完整的可运行示例：/spot/recipes/quickstart。字段级架构：通过 docs MCP 加载 /resources/trading-api/order/order。

应该询问用户什么（以及不应该问什么）

交易信息（明确时可自行推断，不明确时需确认）：

1. 输入和输出代币都使用 base58 铸币地址。CLI 可解析一小组代币符号（SOL、USDC、USDT、JUP、BONK 等）；API 没有符号解析器，只接受 base58 铸币地址。
2. 输入代币的最小单位数量（500000 = 0.50 美元的 USDC，1000000000 = 1 SOL）。调用前先进行换算。

基础设施（始终询问，切勿自行推断）：

3. 仅适用于 API：钱包公钥（base58），每次调用会返回交易的 /order 请求都需要提供。
4. 仅适用于 API：DFlow API 密钥。用简洁、中性的方式询问：“你有 DFlow API 密钥吗？” 不要预设密钥存放的位置；像 “是否已设置 DFLOW_API_KEY？” 这样的问法会引导用户采用他们并未要求的环境变量默认方式。一个密钥即可用于所有 DFlow 服务（同一个 x-api-key 可用于 REST API 和 WebSocket 流）。如果有，使用生产环境主机 https://quote-api.dflow.net，并在每个请求中附上 x-api-key。如果没有，使用开发环境主机 https://dev-quote-api.dflow.net（功能相同，但有速率限制，仅供测试）。提供 https://pond.dflow.net/get-started/api-key 以获取生产环境密钥。dflow CLI 也需要密钥，通过 dflow setup 设置一次即可。
5. 优先费（两个接口都适用）：“你对优先费有什么偏好，还是直接使用 DFlow 的默认值？” 两个接口的默认值都是 DFlow 自动设置，上限为 0.005 SOL（/order 文档中列出的默认值）。告知用户有此选项，以便在网络拥堵或对成本敏感的交易中进行调整。不要评论这适用于多少比例的交易；DFlow 未公布相关数据。
   • API：在 /order 上将 prioritizationFeeLamports 设为 auto、medium、high、veryHigh、disabled 或整数 lamport 数值。可用于调整的实时估算值：GET /priority-fees（快照）、/priority-fees/stream（WebSocket）。通过 docs MCP 加载 /spot/trading/priority-fees，查看费用模式和自动上限。
   • CLI：没有调节选项；dflow trade 始终使用服务端默认值。如需更精细的控制（精确的 lamport 数值或 disabled），请改用 API。
6. 赞助 / 免 Gas（仅适用于 API，CLI 用户无需询问）：“用户需要持有 SOL 来支付这笔交易的费用吗，还是由你的应用承担费用？” 默认由用户支付。如需赞助，在 /order 上传入 sponsor=<sponsor-wallet-base58>，并使用赞助方密钥对为返回的交易共同签名：signTransaction([userKeypair, sponsorKeypair], tx)（用户和赞助方都需要签名）。可选的 sponsorExec=true|false 用于选择由赞助方执行（默认）还是由用户执行。完整语义：通过 docs MCP 加载 /resources/trading-api/order/order。CLI 不支持赞助。

不要询问以下内容：

• RPC：CLI 用户在 dflow setup 时设置。对于 API，仅当应用在服务端签名且需要使用自己的 RPC 提交交易时才询问。需要 RPC 时，使用可靠的 RPC 提供商。
• 滑点：两个接口的默认值都是 "auto"。仅在用户明确要求时覆盖（CLI 使用 --slippage；API 使用 slippageBps）。
• DEX 包含/排除项、路由长度、Jito bundles、仅限直接路由：典型兑换的默认值已足够；仅在用户明确提出需求时才介绍这些选项。
• 平台费用：默认关闭；仅当用户通过自己的分发渠道获利时才相关。请参阅下方的平台费用部分。

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

• 交易格式。 每次 /order（以及 /quote）调用都会构建一笔 4096 字节的交易，其中内联了账户地址（不使用地址查找表），并会拒绝重复地址；64 个账户的限制仍然适用。使用 @solana/kit（>=8.0.0）来构建、签名并发送交易——经典的 @solana/web3.js 可以解码交易以供显示，但无法构建、签名或发送交易。
• 始终使用原子单位。 API 会拒绝人类可读的金额。每次都要确认小数位数（通过代币元数据或 RPC getParsedAccountInfo）。
• API 没有代币符号解析器。 inputMint 和 outputMint 只接受 base58 格式的铸币地址，因此像 "USDC" 这样的代币符号无法用于 /order。（CLI 可以解析少量代币符号；API 不行。）
• 浏览器应用必须使用代理。 Trading API 不提供 CORS，因此应从后端（边缘函数或 API 路由）调用，绝不能直接从浏览器调用。
• route_not_found。 一个可能的原因是以当前交易规模交易该货币对时流动性不足。还应确认铸币地址正确，且 amount 使用的是原子单位。
• price_impact_too_high 是实际错误。 交易规模超出可用流动性；请减小 amount，或仅在获得用户明确同意后传入 priceImpactTolerancePct。
• 链上交易失败并记录了滑点日志。 重试时不要悄悄调高 slippageBps；应将此情况告知用户。
• CLI 和直接 HTTP 使用不同的认证配置。 CLI 会在 dflow setup 时保存密钥、钱包和 RPC，因此通过 shell 执行 dflow trade 不需要额外传入任何内容。直接调用 /order 的同级 HTTP 客户端需要自行传入密钥（环境变量、.env、请求头）；不会复用 CLI 保存的密钥。两者都需要密钥，只是配置位置不同。

平台费用（构建者分成）

对应用路由的兑换收取费用；交易成功执行后，费用会支付到由构建者控制的代币账户。仅限 API：这些是 /order 参数；dflow CLI 没有平台费用标志。

• platformFeeBps：以基点表示的固定费用（50 = 0.5%）。
• platformFeeMode：费用由哪一侧支付，可选 outputMint（默认值）或 inputMint。
• feeAccount：接收费用的 SPL 代币账户。该账户必须已存在（DFlow 不会创建）；你需要为每种收取费用的代币准备一个由构建者钱包拥有的 ATA。每次请求都要传入与所选模式对应的代币账户。

注意事项：

• 除非确实要收取费用，否则不要设置 platformFeeBps。 声明的费用会计入滑点预算，因此如果没有实际可用的 feeAccount，这笔费用会白白占用预算，并使用户获得的价格更差。
• 仅成功的交易会收取费用。 失败或回滚的兑换不会产生费用。

询问用户：费率（基点）、收取费用的代币，以及是否已存在匹配的、由构建者拥有的 ATA。完整的模式矩阵请通过 docs MCP 加载 /spot/trading/platform-fees；可运行示例：/spot/recipes/platform-fees。

遇到不适用的情况

对于此处未涵盖的内容（完整参数列表、完整错误表、赞助字段），请查询 docs MCP（search_d_flow、query_docs_filesystem_d_flow）。

如需可运行的代码，请引导用户查看 DFlow 文档中的示例：/spot/recipes/quickstart。

相关技能

如果用户转而提出以下需求，请转交给对应技能：

• dflow-market-data：实时价格、订单簿或深度数据流。该技能提供只读市场数据；本技能执行交易，那个技能展示交易数据。用户提出“显示实时订单簿／价格”之类的需求时，应使用该技能。