dflow-spot-trading

DFlow Spot Trading

DFlow を使って Solana トークンの任意のペアをスワップします。取引は同期処理です。/order を 1 回呼び出すと、署名可能なトランザクションが返されるので、署名して送信し、確定します。

前提条件

• DFlow docs MCP（https://pond.dflow.net/mcp）：リポジトリの README に従ってインストールします。このスキルは手順書であり、MCP はリファレンスです。エンドポイントの形式、パラメーターの詳細、エラーコードは推測せず、MCP で確認してください。
  • 規則：このスキル内の単独のドキュメントパス（例：/resources/trading-api/order/order）は MCP パスです。query_docs_filesystem_d_flow（.mdx を cat／head する）または search_d_flow で読み込み、ブラウザーから取得しないでください。完全な https:// リンクは人間向けのリンク先（実行可能な手順や API キーの登録ページ）なので、ユーザーに提示します。
• dflow CLI（任意、コマンドライン／エージェントでの使用向け）：リポジトリの README に従ってインストールします。

使用する方法を選択する

• CLI：コマンドライン、スクリプト、ローカルエージェント向けです。キーの管理、署名、ブロードキャストを行います。
• API：独自の署名機能を備えた Web／モバイルアプリ、バックエンド、自動化向けです。ブラウザーアプリでは、Trading API は CORS に対応していないため、HTTP リクエストをバックエンド経由でプロキシする必要があります。

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

ワークフロー

見積もり（読み取り専用）

• CLI：dflow quote <atomic-amount> <FROM> <TO>
• API：GET /order は見積もりにも使えます。userPublicKey を指定せずに呼び出すと、トランザクションを含まずに価格フィールドが返されます。これは、ユーザーがウォレットを接続する前に見積もりを行う場合に必要な動作です。/quote も引き続き動作しますが、新しい統合では /order の使用を推奨します。（見積もり／レスポンスのフィールド一覧：docs MCP で /resources/trading-api/order/order を読み込みます。）

取引（/order）

1 回の呼び出しで見積もりと署名可能なトランザクションを取得し、署名して送信し、確定します。すべての SPL および Token-2022 ミントに対応しています。

完全なリクエスト／レスポンススキーマ、すべてのパラメーター、エラーコードについては、docs MCP で /resources/trading-api/order/order を読み込みます（query_docs_filesystem_d_flow）。

• CLI：dflow trade <atomic-amount> <FROM> <TO>（確定するまで処理をブロックする必要があるエージェント／スクリプトでは、--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、または整数の lamports です。調整用のリアルタイム推定値は GET /priority-fees（スナップショット）と /priority-fees/stream（WebSocket）で取得できます。手数料モードと自動設定の上限については、ドキュメント MCP 経由で /spot/trading/priority-fees を読み込んでください。
   • CLI：調整用のフラグはありません。dflow trade は常にサーバー側のデフォルトを使用します。より細かく制御する場合（lamport 単位での正確な値、または disabled）、API を使用してください。
6. スポンサー負担／ガスレス（API のみ。CLI では確認不要）：「この取引のためにユーザーが SOL を保有する必要がありますか？ それともアプリが手数料を負担しますか？」 デフォルトではユーザーが支払います。スポンサー負担にするには、/order に sponsor=<sponsor-wallet-base58> を指定し、返されたトランザクションにスポンサーのキーペアを使って共同署名します：signTransaction([userKeypair, sponsorKeypair], tx)（ユーザーとスポンサーの両方が署名します）。任意の sponsorExec=true|false で、スポンサーが実行する（デフォルト）か、ユーザーが実行するかを選択できます。詳細な仕様については、ドキュメント MCP 経由で /resources/trading-api/order/order を読み込んでください。CLI はスポンサー負担に対応していません。

確認しないこと：

• RPC：CLI のユーザーは dflow setup 時に設定します。API では、アプリがサーバー側で署名し、送信に独自の RPC が必要な場合にのみ確認してください。必要な場合は、信頼できる RPC プロバイダーを使用してください。
• スリッページ：どちらの方法でもデフォルトは "auto" です。ユーザーから明示的な依頼があった場合のみ上書きしてください（CLI では --slippage、API では slippageBps）。
• DEX の組み込み／除外、ルートの長さ、Jito バンドル、直接ルートのみの指定：一般的なスワップではデフォルトが適切です。ユーザーが明示的に必要としている場合のみ、これらの設定項目を案内してください。
• プラットフォーム手数料：デフォルトでは無効です。自身が提供するサービスを収益化する場合にのみ関係します。以下の「プラットフォーム手数料」セクションを参照してください。

注意点（ドキュメント 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 を保存するため、dflow trade をシェルから実行する際に追加の設定は不要です。一方、/order を直接呼び出す別の HTTP クライアントには、独自のキーを渡す必要があります（環境変数、.env、ヘッダー）。CLI に保存されたキーは再利用されません。どちらにもキーが必要ですが、設定場所が異なります。

プラットフォーム手数料（ビルダーの取り分）

アプリがルーティングするスワップで手数料を徴収できます。手数料は、実行成功時にビルダーが管理するトークンアカウントへ支払われます。API 専用です。これらは /order のパラメーターであり、dflow CLI にプラットフォーム手数料のフラグはありません。

• platformFeeBps：ベーシスポイント単位の定額手数料（50 = 0.5%）。
• platformFeeMode：手数料を支払う側。outputMint（デフォルト）または inputMint。
• feeAccount：手数料を受け取る SPL トークンアカウントです。すでに存在している必要があります（DFlow は作成しません）。徴収対象の各トークンにつき、ビルダーのウォレットが所有する ATA が 1 つ必要です。リクエストごとに、モードで指定したトークンに対応するものを渡してください。

注意点：

• 実際に徴収する場合を除き、platformFeeBps を設定しないでください。 宣言された手数料はスリッページの予算に加味されるため、実際の feeAccount が指定されていない手数料は、その予算を無駄に消費し、ユーザーに不利な価格になります。
• 手数料が適用されるのは取引が成功した場合のみです。 失敗または取り消されたスワップでは手数料はかかりません。

ユーザーに確認する項目：手数料率（bps）、徴収するトークン（および対応するビルダー所有の ATA がすでに存在するかどうか）。モードの全組み合わせについては、ドキュメント MCP で /spot/trading/platform-fees を読み込んでください。実行可能な例：/spot/recipes/platform-fees。

要件に合わない場合

ここに記載されていない内容（全パラメーター一覧、全エラー表、スポンサーシップ関連フィールド）については、ドキュメント MCP（search_d_flow、query_docs_filesystem_d_flow）に問い合わせてください。

実行可能なコードについては、DFlow のドキュメントレシピをユーザーに案内してください：/spot/recipes/quickstart。

関連スキル

ユーザーが以下の内容に切り替えた場合は、該当するスキルに案内してください。

• dflow-market-data：ライブ価格、オーダーブック、または板の厚さをストリーミングします。読み取り専用のマーケットデータです。このスキルは取引を実行し、そちらのスキルは取引を表示します。「ライブの板／価格を見せて」という依頼は、そちらのスキルが担当します。