dflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DFlow - Complete Integration Guide

DFlow - 完整集成指南

The definitive guide for integrating DFlow - a trading protocol that enables traders to exchange value across spot and prediction markets natively on Solana.
这是集成DFlow的权威指南——DFlow是一个交易协议,允许交易者在Solana原生环境中跨现货和预测市场进行价值交换。

What is DFlow?

什么是DFlow?

DFlow is a comprehensive trading infrastructure that provides:
  • Trading Applications & Wallets - Token swaps with intelligent routing and 99.9% token coverage
  • Exchanges & Aggregators - Access to billions in monthly routed volume across DEXes and Prop AMMs
  • Financial Institutions & Market Makers - Programmable execution layers with CLPs and async trades
  • Prediction Market Platforms - Discovery, pricing, routing, and settlement infrastructure
DFlow是一套全面的交易基础设施,提供以下能力:
  • 交易应用与钱包 - 具备智能路由和99.9%代币覆盖的代币交换功能
  • 交易所与聚合器 - 可接入去中心化交易所(DEX)和Prop AMM每月数十亿美元的路由交易量
  • 金融机构与做市商 - 具备CLP和异步交易的可编程执行层
  • 预测市场平台 - 发现、定价、路由和结算基础设施

Key Capabilities

核心能力

FeatureDescription
Token Coverage99.9% with millisecond detection
InfrastructureGlobally distributed, high-throughput optimization
ExecutionAdvanced algorithms with JIT routing for best-price execution
MarketsSupport for both spot and prediction market trading
MEV ProtectionEnhanced sandwich protection with Jito bundles
功能描述
代币覆盖99.9%的代币覆盖,支持毫秒级检测
基础设施全球分布式、高吞吐量优化
执行机制采用先进算法,通过JIT路由实现最优价格执行
市场支持同时支持现货和预测市场交易
MEV防护借助Jito bundle增强三明治攻击防护

API Overview

API概览

DFlow provides two main API categories:
DFlow提供两大类主要API:

1. Swap API (Trading)

1. Swap API(交易类)

Base URL:
https://quote-api.dflow.net
For executing trades:
  • Imperative Swaps - Full control over route selection at signature time
  • Declarative Swaps - Intent-based swaps with deferred route optimization
  • Trade API - Unified interface for spot and prediction market trading
  • Order API - Quote and transaction generation
基础URL:
https://quote-api.dflow.net
用于执行交易:
  • 命令式交换(Imperative Swaps) - 在签名阶段完全控制路由选择
  • 声明式交换(Declarative Swaps) - 基于意图的交换,延迟路由优化
  • Trade API - 统一处理现货和预测市场交易的接口
  • Order API - 报价和交易生成

2. Prediction Market Metadata API

2. 预测市场元数据API

Base URL:
https://api.prod.dflow.net
For querying prediction market data:
  • Events API - Query prediction events and forecasts
  • Markets API - Get market details, orderbooks, outcome mints
  • Trades API - Historical trade data
  • Live Data API - Real-time milestones and updates
  • WebSocket - Streaming price and orderbook updates
基础URL:
https://api.prod.dflow.net
用于查询预测市场数据:
  • Events API - 查询预测事件和预测数据
  • Markets API - 获取市场详情、订单簿、结果代币地址
  • Trades API - 历史交易数据
  • Live Data API - 实时里程碑和更新
  • WebSocket - 流式价格和订单簿更新

Authentication

认证

Most endpoints require an API key via the
x-api-key
header. Contact
hello@dflow.net
to obtain credentials.
大多数端点需要通过
x-api-key
头携带API密钥。请联系
hello@dflow.net
获取凭证。

Quick Start

快速开始

Imperative Swap (3 Steps)

命令式交换(3步)

typescript
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;
}
typescript
import { Connection, Keypair, VersionedTransaction } from "@solana/web3.js";

const API_BASE = "https://quote-api.dflow.net";
const API_KEY = process.env.DFLOW_API_KEY; // 可选但推荐使用

// 代币地址
const SOL = "So11111111111111111111111111111111111111112";
const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

async function imperativeSwap(keypair: Keypair, connection: Connection) {
  // 步骤1:获取报价
  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());

  // 步骤2:获取交换交易
  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());

  // 步骤3:签名并发送
  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 (Unified - Recommended)

Trade API(统一接口 - 推荐使用)

The Trade API provides a single endpoint that handles both sync and async execution:
typescript
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;
}
Trade API提供单一端点,处理同步和异步执行:
typescript
async function tradeTokens(keypair: Keypair, connection: Connection) {
  // 步骤1:获取订单(一次调用同时获取报价和交易)
  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());

  // 步骤2:签名并发送
  const tx = VersionedTransaction.deserialize(
    Buffer.from(order.transaction, "base64")
  );
  tx.sign([keypair]);
  const signature = await connection.sendTransaction(tx);

  // 步骤3:监控(根据执行模式)
  if (order.executionMode === "async") {
    // 轮询异步交易的状态
    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 {
    // 同步交易原子性完成
    await connection.confirmTransaction(signature);
  }

  return signature;
}

API Reference

API参考

Order API Endpoints

Order API端点

GET /order

GET /order

Returns a quote and optionally a transaction for spot or prediction market trades.
ParameterRequiredDescription
inputMint
YesBase58 input token mint
outputMint
YesBase58 output token mint
amount
YesAmount as scaled integer (1 SOL = 1000000000)
userPublicKey
NoInclude to receive signable transaction
slippageBps
NoMax slippage in basis points or "auto"
platformFeeBps
NoPlatform fee in basis points
prioritizationFeeLamports
No"auto", "medium", "high", "veryHigh", or lamport amount
Response:
json
{
  "outAmount": "150000000",
  "minOutAmount": "149250000",
  "priceImpactPct": "0.05",
  "executionMode": "sync",
  "transaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "routePlan": [...]
}
返回现货或预测市场交易的报价,可选返回交易数据。
参数是否必填描述
inputMint
Base58格式的输入代币地址
outputMint
Base58格式的输出代币地址
amount
缩放后的整数金额(1 SOL = 1000000000)
userPublicKey
传入以获取可签名的交易
slippageBps
最大滑点(基点)或"auto"
platformFeeBps
平台手续费(基点)
prioritizationFeeLamports
"auto", "medium", "high", "veryHigh",或具体lamport数值
响应:
json
{
  "outAmount": "150000000",
  "minOutAmount": "149250000",
  "priceImpactPct": "0.05",
  "executionMode": "sync",
  "transaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "routePlan": [...]
}

GET /order-status

GET /order-status

Check status of async orders.
ParameterRequiredDescription
signature
YesBase58 transaction signature
lastValidBlockHeight
NoBlock height for expiry check
Status Values:
  • pending
    - Order submitted, awaiting processing
  • open
    - Order opened, awaiting fill
  • pendingClose
    - Filled, closing transaction pending
  • closed
    - Order completed successfully
  • expired
    - Transaction expired before landing
  • failed
    - Order execution failed
查询异步订单的状态。
参数是否必填描述
signature
Base58格式的交易签名
lastValidBlockHeight
用于过期检查的区块高度
状态值:
  • pending
    - 订单已提交,等待处理
  • open
    - 订单已开启,等待成交
  • pendingClose
    - 订单已成交,关闭交易待处理
  • closed
    - 订单执行成功
  • expired
    - 交易在落地前已过期
  • failed
    - 订单执行失败

Imperative Swap Endpoints

命令式交换端点

GET /quote

GET /quote

Get a quote for an imperative swap.
ParameterRequiredDescription
inputMint
YesBase58 input mint
outputMint
YesBase58 output mint
amount
YesInput amount (scaled integer)
slippageBps
NoSlippage tolerance or "auto"
dexes
NoComma-separated DEXes to include
excludeDexes
NoComma-separated DEXes to exclude
onlyDirectRoutes
NoSingle-leg routes only
maxRouteLength
NoMax number of route legs
forJitoBundle
NoJito bundle compatible routes
platformFeeBps
NoPlatform fee in basis points
获取命令式交换的报价。
参数是否必填描述
inputMint
Base58格式的输入代币地址
outputMint
Base58格式的输出代币地址
amount
输入金额(缩放后的整数)
slippageBps
滑点容忍度或"auto"
dexes
逗号分隔的包含的DEX列表
excludeDexes
逗号分隔的排除的DEX列表
onlyDirectRoutes
仅使用单腿路由
maxRouteLength
路由的最大腿数
forJitoBundle
兼容Jito bundle的路由
platformFeeBps
平台手续费(基点)

POST /swap

POST /swap

Generate swap transaction from quote.
Request Body:
json
{
  "userPublicKey": "Base58...",
  "quoteResponse": { /* from /quote */ },
  "dynamicComputeUnitLimit": true,
  "prioritizationFeeLamports": 150000,
  "wrapAndUnwrapSol": true
}
Response:
json
{
  "swapTransaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "prioritizationFeeLamports": 150000
}
根据报价生成交换交易。
请求体:
json
{
  "userPublicKey": "Base58...",
  "quoteResponse": { /* 来自/quote的响应 */ },
  "dynamicComputeUnitLimit": true,
  "prioritizationFeeLamports": 150000,
  "wrapAndUnwrapSol": true
}
响应:
json
{
  "swapTransaction": "base64...",
  "computeUnitLimit": 200000,
  "lastValidBlockHeight": 123456789,
  "prioritizationFeeLamports": 150000
}

POST /swap-instructions

POST /swap-instructions

Returns individual instructions instead of a full transaction (for custom transaction building).
返回单个交易指令而非完整交易(用于自定义交易构建)。

Declarative Swap Endpoints

声明式交换端点

Declarative swaps use intent-based execution with deferred route optimization.
声明式交换采用基于意图的执行模式,延迟路由优化。

GET /intent

GET /intent

Get an intent quote for a declarative swap.
ParameterRequiredDescription
inputMint
YesBase58 input mint
outputMint
YesBase58 output mint
amount
YesInput amount (scaled integer)
slippageBps
NoSlippage tolerance
userPublicKey
YesUser's wallet address
获取声明式交换的意图报价。
参数是否必填描述
inputMint
Base58格式的输入代币地址
outputMint
Base58格式的输出代币地址
amount
输入金额(缩放后的整数)
slippageBps
滑点容忍度
userPublicKey
用户钱包地址

POST /submit-intent

POST /submit-intent

Submit a signed intent transaction for execution.
Request Body:
json
{
  "signedTransaction": "base64...",
  "intentResponse": { /* from /intent */ }
}
提交已签名的意图交易以执行。
请求体:
json
{
  "signedTransaction": "base64...",
  "intentResponse": { /* 来自/intent的响应 */ }
}

Token API Endpoints

代币API端点

GET /tokens

GET /tokens

Returns list of supported token mints.
返回支持的代币地址列表。

GET /tokens-with-decimals

GET /tokens-with-decimals

Returns tokens with decimal information for proper amount scaling.
返回包含小数位数信息的代币,用于正确的金额缩放。

Venue API Endpoints

交易场所API端点

GET /venues

GET /venues

Returns list of supported DEX venues (Raydium, Orca, Phoenix, Lifinity, etc.).
返回支持的DEX交易场所列表(Raydium、Orca、Phoenix、Lifinity等)。

Swap Modes Comparison

交换模式对比

FeatureImperativeDeclarative
Route ControlFull control at sign timeOptimized at execution
LatencyHigher (two API calls)Lower (deferred calc)
SlippageFixed at quote timeMinimized at execution
Sandwich ProtectionStandardEnhanced
Use CasePrecise route requirementsBest execution priority
特性命令式声明式
路由控制签名阶段完全控制执行阶段优化
延迟较高(两次API调用)较低(延迟计算)
滑点报价时固定执行时最小化
三明治攻击防护标准级别增强级别
使用场景需要精确路由需求优先最优执行

When to Use Imperative

何时使用命令式模式

  • Need to review exact route before signing
  • Building order books or specific DEX routing
  • Complex multi-step transactions
  • Need deterministic execution paths
  • 需要在签名前查看精确路由
  • 构建订单簿或特定DEX路由
  • 复杂的多步交易
  • 需要确定性执行路径

When to Use Declarative

何时使用声明式模式

  • Prioritize best execution
  • Lower slippage requirements
  • Simple token swaps
  • MEV protection is important
  • 优先最优执行
  • 较低滑点要求
  • 简单代币交换
  • MEV防护很重要

Execution Modes

执行模式

Synchronous (Atomic)

同步模式(原子性)

  • Single transaction execution
  • All-or-nothing settlement
  • Standard confirmation flow
  • Use
    connection.confirmTransaction()
  • 单交易执行
  • 全有或全无的结算
  • 标准确认流程
  • 使用
    connection.confirmTransaction()

Asynchronous (Multi-Transaction)

异步模式(多交易)

  • Uses Jito bundles
  • Open → Fill → Close transaction flow
  • Poll
    /order-status
    for completion
  • Better for complex routes or prediction markets
typescript
// 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 };
    }
  }
}
  • 使用Jito bundle
  • 开启→成交→关闭的交易流程
  • 轮询
    /order-status
    获取完成状态
  • 更适合复杂路由或预测市场
typescript
// 异步订单监控
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 };
    }
  }
}

Prediction Markets

预测市场

DFlow provides infrastructure for trading prediction market outcome tokens.
DFlow提供预测市场结果代币的交易基础设施。

Market Structure

市场结构

Series (Collection)
  └── Event (Occurrence)
        └── Market (Outcome Trade)
系列(Series,集合)
  └── 事件(Event,具体事件)
        └── 市场(Market,结果交易)

Market Lifecycle

市场生命周期

  1. Initialized - Market created
  2. Active - Trading enabled
  3. Inactive - Trading paused
  4. Closed - No more trading
  5. Determined - Outcome known
  6. Finalized - Payouts available
  1. Initialized - 市场已创建
  2. Active - 交易已启用
  3. Inactive - 交易已暂停
  4. Closed - 停止交易
  5. Determined - 结果已确定
  6. Finalized - 可进行赔付

Trading Prediction Markets

交易预测市场

typescript
// 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());
typescript
// 使用Trade API交易预测市场代币
const order = await fetch(`${API_BASE}/order?${new URLSearchParams({
  inputMint: USDC,
  outputMint: OUTCOME_TOKEN_MINT, // 预测市场代币
  amount: "10000000", // 10 USDC
  slippageBps: "100",
  userPublicKey: keypair.publicKey.toBase58(),
  predictionMarketSlippageBps: "200", // 预测市场单独设置滑点
})}`, { headers: { "x-api-key": API_KEY } }).then(r => r.json());

Common Token Mints

常见代币地址

TokenMint Address
SOL (Wrapped)
So11111111111111111111111111111111111111112
USDC
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT
Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
BONK
DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
JUP
JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
WIF
EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm
代币地址
SOL(Wrapped)
So11111111111111111111111111111111111111112
USDC
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT
Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
BONK
DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
JUP
JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
WIF
EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm

Priority Fees

优先级手续费

Configure transaction priority:
typescript
// 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
}
配置交易优先级:
typescript
// 选项1:自动(推荐)
prioritizationFeeLamports: "auto"

// 选项2:优先级级别
prioritizationFeeLamports: {
  priorityLevel: "high" // "medium", "high", "veryHigh"
}

// 选项3:精确金额
prioritizationFeeLamports: 150000

// 选项4:自动调整的最大金额
prioritizationFeeLamports: {
  autoMultiplier: 2,
  maxLamports: 500000
}

Error Handling

错误处理

typescript
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 };
  }
}
typescript
async function safeSwap(params: SwapParams) {
  try {
    const quote = await getQuote(params);

    if (!quote.routePlan?.length) {
      throw new Error("未找到路由");
    }

    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: "余额不足" };
    }
    if (error.message.includes("slippage")) {
      return { success: false, error: "滑点超出限制" };
    }
    return { success: false, error: error.message };
  }
}

Platform Fees

平台手续费

Collect platform fees on swaps:
typescript
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());
在交换中收取平台手续费:
typescript
const quote = await fetch(`${API_BASE}/quote?${new URLSearchParams({
  inputMint: SOL,
  outputMint: USDC,
  amount: "1000000000",
  platformFeeBps: "50", // 0.5%手续费
  platformFeeMode: "outputMint", // 收取输出代币作为手续费
})}`, { headers: { "x-api-key": API_KEY } }).then(r => r.json());

// 在交换请求中指定手续费接收账户
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(), // 你的手续费接收账户
  }),
}).then(r => r.json());

Jito Integration

Jito集成

For MEV protection and bundle submission:
typescript
// 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());
用于MEV防护和bundle提交:
typescript
// 请求兼容Jito的路由
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());

// 包含Jito三明治攻击缓解
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交换编排器

The DFlow Swap Orchestrator contract manages declarative swap execution:
Program ID: DF1ow3DqMj3HvTj8i8J9yM2hE9hCrLLXpdbaKZu4ZPnz

DFlow交换编排器合约管理声明式交换的执行:
程序ID: DF1ow3DqMj3HvTj8i8J9yM2hE9hCrLLXpdbaKZu4ZPnz

Prediction Market Metadata API

预测市场元数据API

The Prediction Market Metadata API provides comprehensive access to prediction market information.
Base URL:
https://api.prod.dflow.net
预测市场元数据API提供对预测市场信息的全面访问。
基础URL:
https://api.prod.dflow.net

Market Structure

市场结构

Series (Collection)
  └── Event (Occurrence)
        └── Market (Outcome Trade)
              ├── Yes Token (outcome mint)
              └── No Token (outcome mint)
系列(Series,集合)
  └── 事件(Event,具体事件)
        └── 市场(Market,结果交易)
              ├── Yes Token(结果代币地址)
              └── No Token(结果代币地址)

Events API

Events API

GET /api/v1/event/{ticker}

GET /api/v1/event/{ticker}

Returns a single event by its ticker with optional nested markets.
typescript
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.
通过交易代码返回单个事件,可选返回嵌套的市场数据。
typescript
const METADATA_API = "https://api.prod.dflow.net";

// 获取事件详情
const event = await fetch(`${METADATA_API}/api/v1/event/TRUMP-2024`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());

// 响应包含:交易代码、标题、状态、市场、关闭时间等

GET /api/v1/events

GET /api/v1/events

Returns a paginated list of all events.
typescript
const events = await fetch(`${METADATA_API}/api/v1/events?limit=50&offset=0`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());
返回所有事件的分页列表。
typescript
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}/forecast

Returns historical forecast percentile data.
返回历史预测百分位数数据。

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

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

Returns candlestick data from Kalshi.
返回来自Kalshi的K线数据。

Markets API

Markets API

GET /api/v1/market/{ticker}

GET /api/v1/market/{ticker}

Returns a single market by ticker.
typescript
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.
通过交易代码返回单个市场。
typescript
const market = await fetch(`${METADATA_API}/api/v1/market/TRUMP-2024-WIN`, {
  headers: { "x-api-key": API_KEY }
}).then(r => r.json());

// 响应:交易代码、yes代币地址、no代币地址、状态、最新价格、交易量等

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

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

Lookup market by any mint (ledger or outcome mints).
typescript
const market = await fetch(
  `${METADATA_API}/api/v1/market/by-mint/${outcomeMint}`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());
通过代币地址查询市场(账本代币或结果代币)。
typescript
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

POST /api/v1/markets/batch

Batch retrieve multiple markets (max 100).
typescript
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());
批量获取多个市场(最多100个)。
typescript
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

GET /api/v1/outcome_mints

Returns all yes_mint and no_mint pubkeys from all supported markets.
typescript
// 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());
返回所有支持市场的yes代币和no代币地址。
typescript
// 获取所有结果代币,可选按关闭时间过滤
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

POST /api/v1/filter_outcome_mints

Check if addresses are outcome mints (max 200).
typescript
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());
检查地址是否为结果代币(最多200个)。
typescript
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());

Orderbook API

订单簿API

GET /api/v1/orderbook/{ticker}

GET /api/v1/orderbook/{ticker}

Get orderbook by market ticker.
typescript
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}]
通过市场交易代码获取订单簿。
typescript
const orderbook = await fetch(
  `${METADATA_API}/api/v1/orderbook/TRUMP-2024-WIN`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

// 响应:bids: [{price, quantity}], asks: [{price, quantity}]

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

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

Get orderbook using mint address lookup.
通过代币地址查询订单簿。

Trades API

交易API

GET /api/v1/trades

GET /api/v1/trades

Returns paginated trade history with filtering.
typescript
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());
返回带过滤条件的分页交易历史。
typescript
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}

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

Get trades using mint address lookup.
通过代币地址查询交易。

Live Data API

实时数据API

GET /api/v1/milestones/{ticker}

GET /api/v1/milestones/{ticker}

Real-time milestone data from Kalshi.
typescript
const milestones = await fetch(
  `${METADATA_API}/api/v1/milestones/TRUMP-2024`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());
来自Kalshi的实时里程碑数据。
typescript
const milestones = await fetch(
  `${METADATA_API}/api/v1/milestones/TRUMP-2024`,
  { headers: { "x-api-key": API_KEY } }
).then(r => r.json());

Series & Categories

系列与分类

GET /api/v1/series

GET /api/v1/series

Returns series templates for recurring events.
返回重复事件的系列模板。

GET /api/v1/categories

GET /api/v1/categories

Returns category tags for filtering.
返回用于过滤的分类标签。

WebSocket Streaming

WebSocket流

Connect for real-time updates:
typescript
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);
};
连接以获取实时更新:
typescript
const ws = new WebSocket("wss://api.prod.dflow.net/ws");

ws.onopen = () => {
  // 订阅市场更新
  ws.send(JSON.stringify({
    action: "subscribe",
    channel: "market",
    ticker: "TRUMP-2024-WIN"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 处理:price_update, orderbook_update, trade等
  console.log("更新:", data);
};

Market Lifecycle

市场生命周期

StatusDescription
initialized
Market created
active
Trading enabled
inactive
Trading paused
closed
No more trading
determined
Outcome known
finalized
Payouts available

状态描述
initialized
市场已创建
active
交易已启用
inactive
交易已暂停
closed
停止交易
determined
结果已确定
finalized
可进行赔付

GitHub Tools & SDKs

GitHub工具与SDK

DFlow provides several open-source tools on GitHub:
DFlow在GitHub上提供多个开源工具:

solana-agent-kit

solana-agent-kit

Toolkit enabling AI agents to connect to Solana protocols:
typescript
// 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.
用于AI Agent连接Solana协议的工具包:
typescript
// 与AI Agent配合实现自动化交易
import { SolanaAgentKit } from "@dflow/solana-agent-kit";

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

// Agent可以执行DFlow交换、查询市场等操作

clearpools

clearpools

Orca Whirlpools with support for flow segmentation:
typescript
// Extends Orca protocol with DFlow routing
import { ClearPools } from "@dflow/clearpools";

const pools = new ClearPools(connection);
await pools.initializePool(/* params */);
支持流分割的Orca Whirlpools扩展:
typescript
// 扩展Orca协议以支持DFlow路由
import { ClearPools } from "@dflow/clearpools";

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

dflow-amm-interface

dflow-amm-interface

Rust trait definitions for DFlow's AMM implementation. Use when building custom AMMs that integrate with DFlow routing.
DFlow AMM实现的Rust trait定义。用于构建与DFlow路由集成的自定义AMM。

Infrastructure Tools

基础设施工具

  • solana-accountsdb-plugin-bigtable - Geyser plugin for Bigtable
  • solana-bigtable-connection - Bigtable connection library
  • solana-bigtable-geyser-models - Object models for Geyser data

  • solana-accountsdb-plugin-bigtable - 用于Bigtable的Geyser插件
  • solana-bigtable-connection - Bigtable连接库
  • solana-bigtable-geyser-models - Geyser数据的对象模型

Skill Structure

技能结构

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
dflow/
├── SKILL.md                           # 本文档 - 完整集成指南
├── resources/
│   ├── api-reference.md               # Swap API参考
│   ├── prediction-market-api.md       # 预测市场元数据API参考
│   ├── github-sdks.md                 # GitHub工具与SDK文档
│   ├── token-mints.md                 # 常见代币地址
│   └── error-codes.md                 # 错误处理指南
├── examples/
│   ├── imperative-swaps/              # 命令式交换示例
│   ├── declarative-swaps/             # 声明式交换示例
│   ├── trade-api/                     # 统一Trade API示例
│   └── prediction-markets/            # 预测市场示例
│       ├── query-markets.ts           # 查询事件、市场、订单簿
│       ├── trade-outcomes.ts          # 交易结果代币
│       └── websocket-client.ts        # 实时数据流
├── templates/
│   ├── swap-client.ts                 # 交换客户端模板
│   └── prediction-market-client.ts    # 预测市场客户端模板
└── docs/
    ├── advanced-patterns.md           # 复杂集成
    └── troubleshooting.md             # 常见问题

Guidelines

指南

  1. Use Trade API for most cases - Unified endpoint handles both sync/async
  2. Always handle async orders - Check
    executionMode
    and poll status
  3. Set appropriate slippage - "auto" for convenience, custom for control
  4. Include priority fees - Essential for reliable execution
  5. Handle errors gracefully - Network issues, slippage, insufficient balance
  6. Monitor rate limits - Use API key for production
  7. Test on devnet first - DFlow supports Solana devnet
  1. 大多数场景使用Trade API - 统一端点处理同步/异步执行
  2. 务必处理异步订单 - 检查
    executionMode
    并轮询状态
  3. 设置合适的滑点 - "auto"方便快捷,自定义滑点更可控
  4. 包含优先级手续费 - 这是可靠执行的关键
  5. 优雅处理错误 - 网络问题、滑点超出、余额不足等
  6. 监控速率限制 - 生产环境使用API密钥
  7. 先在devnet测试 - DFlow支持Solana devnet

Resources

资源