dflow

DFlow - 完整集成指南

DFlow 集成权威指南——DFlow 是一种交易协议，可让交易者在 Solana 上原生地跨现货市场和预测市场交换价值。

什么是 DFlow？

DFlow 是一套全面的交易基础设施，提供：

• 交易应用与钱包 - 通过智能路由进行代币兑换，代币覆盖率达 99.9%
• 交易所与聚合器 - 接入 DEX 和 Prop AMM 每月数十亿美元的路由交易量
• 金融机构与做市商 - 借助 CLP 和异步交易实现可编程执行层
• 预测市场平台 - 提供发现、定价、路由和结算基础设施

核心能力

特性	说明
代币覆盖率	99.9%，可在毫秒级检测
基础设施	全球分布式架构，高吞吐量优化
执行	采用 JIT 路由的高级算法，实现最佳价格执行
市场	支持现货交易和预测市场交易
MEV 保护	借助 Jito bundles 增强三明治攻击防护

API 概览

DFlow 提供两大类 API：

1. Swap API（交易）

基础 URL： https://quote-api.dflow.net

用于执行交易：

• 命令式兑换 - 在签名时完全控制路由选择
• 声明式兑换 - 基于意图的兑换，可延后优化路由
• Trade API - 现货交易和预测市场交易的统一接口
• Order API - 生成报价和交易

2. 预测市场元数据 API

基础 URL： https://api.prod.dflow.net

用于查询预测市场数据：

• Events API - 查询预测事件和预测结果
• Markets API - 获取市场详情、订单簿和结果铸币地址
• Trades API - 历史交易数据
• Live Data API - 实时里程碑和更新
• WebSocket - 流式推送价格和订单簿更新

身份验证

大多数端点都需要通过 x-api-key 请求头提供 API 密钥。请联系 [email protected] 获取凭据。

快速入门

命令式兑换（3 步）

import { Connection, Keypair, VersionedTransaction } from "@solana/web3.js";

const API_BASE = "https://quote-api.dflow.net";
const API_KEY = process.env.DFLOW_API_KEY; // Optional but recommended

// Token addresses
const SOL = "So11111111111111111111111111111111111111112";
const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

async function imperativeSwap(keypair: Keypair, connection: Connection) {
  // Step 1: Get Quote
  const quoteParams = new URLSearchParams({
    inputMint: SOL,
    outputMint: USDC,
    amount: "1000000000", // 1 SOL
    slippageBps: "50",    // 0.5%
  });

  const quote = await fetch(`${API_BASE}/quote?${quoteParams}`, {
    headers: API_KEY ? { "x-api-key": API_KEY } : {},
  }).then(r => r.json());

  // Step 2: Get Swap Transaction
  const swapResponse = await fetch(`${API_BASE}/swap`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      ...(API_KEY && { "x-api-key": API_KEY }),
    },
    body: JSON.stringify({
      userPublicKey: keypair.publicKey.toBase58(),
      quoteResponse: quote,
      dynamicComputeUnitLimit: true,
      prioritizationFeeLamports: 150000,
    }),
  }).then(r => r.json());

  // Step 3: Sign and Send
  const tx = VersionedTransaction.deserialize(
    Buffer.from(swapResponse.swapTransaction, "base64")
  );
  tx.sign([keypair]);

  const signature = await connection.sendTransaction(tx);
  await connection.confirmTransaction(signature);

  return signature;
}

Trade API（统一接口 - 推荐）

Trade API 提供单个端点，可处理同步和异步执行：

async function tradeTokens(keypair: Keypair, connection: Connection) {
  // Step 1: Get Order (quote + transaction in one call)
  const orderParams = new URLSearchParams({
    inputMint: SOL,
    outputMint: USDC,
    amount: "1000000000",
    slippageBps: "50",
    userPublicKey: keypair.publicKey.toBase58(),
  });

  const order = await fetch(`${API_BASE}/order?${orderParams}`, {
    headers: API_KEY ? { "x-api-key": API_KEY } : {},
  }).then(r => r.json());

  // Step 2: Sign and Send
  const tx = VersionedTransaction.deserialize(
    Buffer.from(order.transaction, "base64")
  );
  tx.sign([keypair]);
  const signature = await connection.sendTransaction(tx);

  // Step 3: Monitor (based on execution mode)
  if (order.executionMode === "async") {
    // Poll order status for async trades
    let status = "pending";
    while (status !== "closed" && status !== "failed") {
      await new Promise(r => setTimeout(r, 2000));
      const statusRes = await fetch(
        `${API_BASE}/order-status?signature=${signature}`,
        { headers: API_KEY ? { "x-api-key": API_KEY } : {} }
      ).then(r => r.json());
      status = statusRes.status;
    }
  } else {
    // Sync trades complete atomically
    await connection.confirmTransaction(signature);
  }

  return signature;
}

API 参考

Order API 端点

GET /order

返回现货或预测市场交易的报价，并可选择返回交易。

参数	必填	说明
inputMint	是	Base58 格式的输入代币铸币地址
outputMint	是	Base58 格式的输出代币铸币地址
amount	是	按缩放整数表示的金额（1 SOL = 1000000000）
userPublicKey	否	提供此参数以接收可签名交易
slippageBps	否	最大滑点，单位为基点，或设置为 "auto"
platformFeeBps	否	平台费用，单位为基点
prioritizationFeeLamports	否	设置为 "auto"、"medium"、"high"、"veryHigh" 或 lamport 数量

响应：

{
  "outAmount": "150000000",
  "minOutAmount": "149250000",
  "priceImpactPct": "0.05",
  "executionMode": "sync",
  "transaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "routePlan": [...]
}

GET /order-status

检查异步订单状态。

参数	必填	说明
signature	是	Base58 格式的交易签名
lastValidBlockHeight	否	用于检查是否过期的区块高度

状态值：

• pending - 订单已提交，等待处理
• open - 订单已开启，等待成交
• pendingClose - 订单已成交，平仓交易待处理
• closed - 订单已成功完成
• expired - 交易在上链前已过期
• failed - 订单执行失败

命令式兑换端点

GET /quote

获取即时交换的报价。

参数	必填	说明
inputMint	是	Base58 输入铸币地址
outputMint	是	Base58 输出铸币地址
amount	是	输入金额（缩放后的整数）
slippageBps	否	滑点容差或 "auto"
dexes	否	要包含的 DEX，逗号分隔
excludeDexes	否	要排除的 DEX，逗号分隔
onlyDirectRoutes	否	仅使用单段路由
maxRouteLength	否	路由段数上限
forJitoBundle	否	与 Jito bundle 兼容的路由
platformFeeBps	否	平台费用（基点）

POST /swap

根据报价生成交换交易。

请求正文：

{
  "userPublicKey": "Base58...",
  "quoteResponse": { /* from /quote */ },
  "dynamicComputeUnitLimit": true,
  "prioritizationFeeLamports": 150000,
  "wrapAndUnwrapSol": true
}

响应：

{
  "swapTransaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "prioritizationFeeLamports": 150000
}

POST /swap-instructions

返回单条指令，而非完整交易（用于自定义交易构建）。

声明式交换端点

声明式交换使用基于意图的执行方式，并延迟优化路由。

GET /intent

获取声明式交换的意图报价。

参数	必填	说明
inputMint	是	Base58 输入铸币地址
outputMint	是	Base58 输出铸币地址
amount	是	输入金额（缩放后的整数）
slippageBps	否	滑点容差
userPublicKey	是	用户的钱包地址

POST /submit-intent

提交已签名的意图交易以供执行。

请求正文：

{
  "signedTransaction": "base64...",
  "intentResponse": { /* from /intent */ }
}

代币 API 端点

GET /tokens

返回受支持的代币铸币地址列表。

GET /tokens-with-decimals

返回包含小数位数信息的代币，以便正确缩放金额。

交易场所 API 端点

GET /venues

返回受支持的 DEX 交易场所列表（Raydium、Orca、Phoenix、Lifinity 等）。

交换模式对比

功能	即时执行	声明式
路由控制	签名时完全控制	执行时优化
延迟	较高（两次 API 调用）	较低（延迟计算）
滑点	报价时固定	执行时尽量降低
抢先交易保护	标准	增强
使用场景	对路由有精确要求	优先获得最佳执行

何时使用即时执行

• 需要在签名前检查确切路由
• 构建订单簿或指定 DEX 路由
• 复杂的多步骤交易
• 需要确定性的执行路径

何时使用声明式

• 优先获得最佳执行
• 对滑点要求更低
• 简单的代币交换
• 需要 MEV 保护

执行模式

同步（原子）

• 单笔交易执行
• 全有或全无的结算
• 标准确认流程
• 使用 connection.confirmTransaction()

异步（多笔交易）

• 使用 Jito bundles
• Open → Fill → Close 交易流程
• 轮询 /order-status 以查看是否完成
• 更适用于复杂路由或预测市场

// Async order monitoring
async function monitorAsyncOrder(signature: string) {
  const statuses = ["pending", "open", "pendingClose"];
  let currentStatus = "pending";

  while (statuses.includes(currentStatus)) {
    await new Promise(r => setTimeout(r, 2000));

    const res = await fetch(
      `${API_BASE}/order-status?signature=${signature}`,
      { headers: { "x-api-key": API_KEY } }
    ).then(r => r.json());

    currentStatus = res.status;

    if (currentStatus === "closed") {
      return { success: true, fills: res.fills };
    }
    if (currentStatus === "failed" || currentStatus === "expired") {
      return { success: false, status: currentStatus };
    }
  }
}

预测市场

DFlow 为预测市场结果代币交易提供基础设施。

市场结构

Series (Collection)
  └── Event (Occurrence)
        └── Market (Outcome Trade)

市场生命周期

1. 已初始化 - 市场已创建
2. 活跃 - 已启用交易
3. 非活跃 - 交易已暂停
4. 已关闭 - 不再进行交易
5. 已确定 - 结果已知
6. 已结算 - 可领取收益

交易预测市场

// Use the Trade API with prediction market token mints
const order = await fetch(`${API_BASE}/order?${new URLSearchParams({
  inputMint: USDC,
  outputMint: OUTCOME_TOKEN_MINT, // Prediction market token
  amount: "10000000", // 10 USDC
  slippageBps: "100",
  userPublicKey: keypair.publicKey.toBase58(),
  predictionMarketSlippageBps: "200", // Separate slippage for PM
})}`, { headers: { "x-api-key": API_KEY } }).then(r => r.json());

常见代币铸币地址

代币	铸币地址
SOL（封装）	So11111111111111111111111111111111111111112
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
BONK	DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
JUP	JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
WIF	EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm

优先费用

配置交易优先级：

// Option 1: Auto (recommended)
prioritizationFeeLamports: "auto"

// Option 2: Priority level
prioritizationFeeLamports: {
  priorityLevel: "high" // "medium", "high", "veryHigh"
}

// Option 3: Exact amount
prioritizationFeeLamports: 150000

// Option 4: Max with auto-adjust
prioritizationFeeLamports: {
  autoMultiplier: 2,
  maxLamports: 500000
}

错误处理

async function safeSwap(params: SwapParams) {
  try {
    const quote = await getQuote(params);

    if (!quote.routePlan?.length) {
      throw new Error("No route found");
    }

    const swap = await getSwapTransaction(quote, params.userPublicKey);
    const tx = deserializeTransaction(swap.swapTransaction);
    tx.sign([params.keypair]);

    const signature = await connection.sendTransaction(tx, {
      skipPreflight: false,
      maxRetries: 3,
    });

    return { success: true, signature };
  } catch (error) {
    if (error.message.includes("insufficient")) {
      return { success: false, error: "Insufficient balance" };
    }
    if (error.message.includes("slippage")) {
      return { success: false, error: "Slippage exceeded" };
    }
    return { success: false, error: error.message };
  }
}

平台费用

在交换中收取平台费用：

const quote = await fetch(`${API_BASE}/quote?${new URLSearchParams({
  inputMint: SOL,
  outputMint: USDC,
  amount: "1000000000",
  platformFeeBps: "50", // 0.5% fee
  platformFeeMode: "outputMint", // Collect in output token
})}`, { headers: { "x-api-key": API_KEY } }).then(r => r.json());

// In swap request, specify fee account
const swap = await fetch(`${API_BASE}/swap`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({
    userPublicKey: user.toBase58(),
    quoteResponse: quote,
    feeAccount: platformFeeAccount.toBase58(), // Your fee recipient
  }),
}).then(r => r.json());

Jito 集成

用于 MEV 保护和 bundle 提交：

// Request Jito-compatible routes
const quote = await fetch(`${API_BASE}/quote?${new URLSearchParams({
  inputMint: SOL,
  outputMint: USDC,
  amount: "1000000000",
  forJitoBundle: "true",
})}`, { headers: { "x-api-key": API_KEY } }).then(r => r.json());

// Include Jito sandwich mitigation
const swap = await fetch(`${API_BASE}/swap`, {
  method: "POST",
  body: JSON.stringify({
    userPublicKey: user.toBase58(),
    quoteResponse: quote,
    includeJitoSandwichMitigationAccount: true,
  }),
}).then(r => r.json());

DFlow Swap Orchestrator

DFlow Swap Orchestrator 合约负责管理声明式 Swap 执行：

Program ID: DF1ow3DqMj3HvTj8i8J9yM2hE9hCrLLXpdbaKZu4ZPnz

---

Prediction Market Metadata API

Prediction Market Metadata API 提供对预测市场信息的全面访问。

基础 URL： https://api.prod.dflow.net

市场结构

Series (Collection)
  └── Event (Occurrence)
        └── Market (Outcome Trade)
              ├── Yes Token (outcome mint)
              └── No Token (outcome mint)

事件 API

GET /api/v1/event/{ticker}

根据 ticker 返回单个事件，可选择包含嵌套市场。

const METADATA_API = "https://api.prod.dflow.net";

// Get event details
const event = await fetch(`${METADATA_API}/api/v1/event/TRUMP-2024`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());

// Response includes: ticker, title, status, markets, close_time, etc.

GET /api/v1/events

返回所有事件的分页列表。

const events = await fetch(`${METADATA_API}/api/v1/events?limit=50&offset=0`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());

GET /api/v1/event/{ticker}/forecast

返回历史预测百分位数据。

GET /api/v1/event/{ticker}/candlesticks

返回来自 Kalshi 的蜡烛图数据。

市场 API

GET /api/v1/market/{ticker}

根据 ticker 返回单个市场。

const market = await fetch(`${METADATA_API}/api/v1/market/TRUMP-2024-WIN`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());

// Response: ticker, yes_mint, no_mint, status, last_price, volume, etc.

GET /api/v1/market/by-mint/{mint_address}

根据任意 mint（账本或结果 mint）查找市场。

const market = await fetch(
  `${METADATA_API}/api/v1/market/by-mint/${outcomeMint}`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

POST /api/v1/markets/batch

批量检索多个市场（最多 100 个）。

const markets = await fetch(`${METADATA_API}/api/v1/markets/batch`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({
    tickers: ["MARKET-1", "MARKET-2"],
    mints: ["mint1...", "mint2..."]
  })
}).then(r => r.json());

GET /api/v1/outcome_mints

返回所有受支持市场的全部 yes_mint 和 no_mint 公钥。

// Get all outcome mints, optionally filter by close time
const mints = await fetch(
  `${METADATA_API}/api/v1/outcome_mints?min_close_timestamp=${Date.now()}`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

POST /api/v1/filter_outcome_mints

检查地址是否为结果 mint（最多 200 个）。

const filtered = await fetch(`${METADATA_API}/api/v1/filter_outcome_mints`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ addresses: ["mint1...", "mint2..."] })
}).then(r => r.json());

订单簿 API

GET /api/v1/orderbook/{ticker}

根据市场 ticker 获取订单簿。

const orderbook = await fetch(
  `${METADATA_API}/api/v1/orderbook/TRUMP-2024-WIN`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

// Response: bids: [{price, quantity}], asks: [{price, quantity}]

GET /api/v1/orderbook/by-mint/{mint_address}

通过 mint 地址查找并获取订单簿。

交易 API

GET /api/v1/trades

返回可筛选的分页交易历史记录。

const trades = await fetch(
  `${METADATA_API}/api/v1/trades?ticker=TRUMP-2024-WIN&limit=100`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

GET /api/v1/trades/by-mint/{mint_address}

通过 mint 地址查找并获取交易记录。

实时数据 API

GET /api/v1/milestones/{ticker}

来自 Kalshi 的实时里程碑数据。

const milestones = await fetch(
  `${METADATA_API}/api/v1/milestones/TRUMP-2024`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

系列与类别

GET /api/v1/series

返回定期事件的系列模板。

GET /api/v1/categories

返回用于筛选的类别标签。

WebSocket 流式传输

连接以获取实时更新：

const ws = new WebSocket("wss://api.prod.dflow.net/ws");

ws.onopen = () => {
  // Subscribe to market updates
  ws.send(JSON.stringify({
    action: "subscribe",
    channel: "market",
    ticker: "TRUMP-2024-WIN"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Handle: price_update, orderbook_update, trade, etc.
  console.log("Update:", data);
};

市场生命周期

状态	说明
initialized	市场已创建
active	已启用交易
inactive	交易已暂停
closed	不再进行交易
determined	结果已知
finalized	可领取收益

---

GitHub 工具与 SDK

DFlow 在 GitHub 上提供了多个开源工具：

solana-agent-kit

代码库： DFlowProtocol/solana-agent-kit

使 AI Agent 能够连接到 Solana 协议的工具包：

// Use with AI agents for automated trading
import { SolanaAgentKit } from "@dflow/solana-agent-kit";

const agent = new SolanaAgentKit({
  rpcUrl: process.env.RPC_URL,
  privateKey: process.env.PRIVATE_KEY,
});

// Agent can execute DFlow swaps, query markets, etc.

clearpools

代码库： DFlowProtocol/clearpools

支持流量分段的 Orca Whirlpools：

// Extends Orca protocol with DFlow routing
import { ClearPools } from "@dflow/clearpools";

const pools = new ClearPools(connection);
await pools.initializePool(/* params */);

dflow-amm-interface

代码库： DFlowProtocol/dflow-amm-interface

DFlow AMM 实现的 Rust trait 定义。构建可接入 DFlow 路由的自定义 AMM 时可使用。

---

技能结构

dflow/
├── SKILL.md                           # This file - complete integration guide
├── resources/
│   ├── api-reference.md               # Swap API reference
│   ├── prediction-market-api.md       # Prediction Market Metadata API reference
│   ├── github-sdks.md                 # GitHub tools & SDKs documentation
│   ├── token-mints.md                 # Common token addresses
│   └── error-codes.md                 # Error handling guide
├── examples/
│   ├── imperative-swaps/              # Imperative swap examples
│   ├── declarative-swaps/             # Declarative swap examples
│   ├── trade-api/                     # Unified Trade API examples
│   └── prediction-markets/            # Prediction market examples
│       ├── query-markets.ts           # Query events, markets, orderbook
│       ├── trade-outcomes.ts          # Trade outcome tokens
│       └── websocket-client.ts        # Real-time data streaming
├── templates/
│   ├── swap-client.ts                 # Swap client starter
│   └── prediction-market-client.ts    # Prediction market client starter
└── docs/
    ├── advanced-patterns.md           # Complex integrations
    └── troubleshooting.md             # Common issues

指南

1. 大多数情况下使用 Trade API - 统一端点可处理同步和异步请求
2. 始终处理异步订单 - 检查 executionMode 并轮询状态
3. 设置合适的滑点 - 为方便起见使用 “auto”，需要控制时使用自定义值
4. 包含优先费 - 这是确保可靠执行的关键
5. 妥善处理错误 - 网络问题、滑点、余额不足
6. 监控速率限制 - 在生产环境中使用 API 密钥
7. 先在 devnet 上测试 - DFlow 支持 Solana devnet

资源

• DFlow 文档
• API 密钥
• Discord 社区
• GitHub