Complete DFlow trading protocol SDK - the single source of truth for integrating DFlow on Solana. Covers spot trading, prediction markets, Swap API, Metadata API, WebSocket streaming, and all DFlow tools.
npxskills add sendaifun/skills--skill dflowLoading…
The definitive guide for integrating DFlow - a trading protocol that enables traders to exchange value across spot and prediction markets natively on Solana.
DFlow is a comprehensive trading infrastructure that provides:
| Feature | Description |
|---|---|
| Token Coverage | 99.9% with millisecond detection |
| Infrastructure | Globally distributed, high-throughput optimization |
| Execution | Advanced algorithms with JIT routing for best-price execution |
| Markets | Support for both spot and prediction market trading |
| MEV Protection | Enhanced sandwich protection with Jito bundles |
DFlow provides two main API categories:
Base URL: https://quote-api.dflow.net
For executing trades:
Base URL: https://api.prod.dflow.net
For querying prediction market data:
Most endpoints require an API key via the x-api-key header. Contact [email protected] to obtain credentials.
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;
}
The Trade API provides a single endpoint that handles both sync and async execution:
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;
}
Returns a quote and optionally a transaction for spot or prediction market trades.
| Parameter | Required | Description |
|---|---|---|
inputMint | Yes | Base58 input token mint |
outputMint | Yes | Base58 output token mint |
amount | Yes | Amount as scaled integer (1 SOL = 1000000000) |
userPublicKey | No | Include to receive signable transaction |
slippageBps | No | Max slippage in basis points or "auto" |
platformFeeBps | No | Platform fee in basis points |
prioritizationFeeLamports | No | "auto", "medium", "high", "veryHigh", or lamport amount |
Response:
{
"outAmount": "150000000",
"minOutAmount": "149250000",
"priceImpactPct": "0.05",
"executionMode": "sync",
"transaction": "base64...",
"computeUnitLimit": 200000,
"lastValidBlockHeight": 123456789,
"routePlan": [...]
}
Check status of async orders.
| Parameter | Required | Description |
|---|---|---|
signature | Yes | Base58 transaction signature |
lastValidBlockHeight | No | Block height for expiry check |
Status Values:
pending - Order submitted, awaiting processingopen - Order opened, awaiting fillpendingClose - Filled, closing transaction pendingclosed - Order completed successfullyexpired - Transaction expired before landingfailed - Order execution failedGet a quote for an imperative swap.
| Parameter | Required | Description |
|---|---|---|
inputMint | Yes | Base58 input mint |
outputMint | Yes | Base58 output mint |
amount | Yes | Input amount (scaled integer) |
slippageBps | No | Slippage tolerance or "auto" |
dexes | No | Comma-separated DEXes to include |
excludeDexes | No | Comma-separated DEXes to exclude |
onlyDirectRoutes | No | Single-leg routes only |
maxRouteLength | No | Max number of route legs |
forJitoBundle | No | Jito bundle compatible routes |
platformFeeBps | No | Platform fee in basis points |
Generate swap transaction from quote.
Request Body:
{
"userPublicKey": "Base58...",
"quoteResponse": { /* from /quote */ },
"dynamicComputeUnitLimit": true,
"prioritizationFeeLamports": 150000,
"wrapAndUnwrapSol": true
}
Response:
{
"swapTransaction": "base64...",
"computeUnitLimit": 200000,
"lastValidBlockHeight": 123456789,
"prioritizationFeeLamports": 150000
}
Returns individual instructions instead of a full transaction (for custom transaction building).
Declarative swaps use intent-based execution with deferred route optimization.
Get an intent quote for a declarative swap.
| Parameter | Required | Description |
|---|---|---|
inputMint | Yes | Base58 input mint |
outputMint | Yes | Base58 output mint |
amount | Yes | Input amount (scaled integer) |
slippageBps | No | Slippage tolerance |
userPublicKey | Yes | User's wallet address |
Submit a signed intent transaction for execution.
Request Body:
{
"signedTransaction": "base64...",
"intentResponse": { /* from /intent */ }
}
Returns list of supported token mints.
Returns tokens with decimal information for proper amount scaling.
Returns list of supported DEX venues (Raydium, Orca, Phoenix, Lifinity, etc.).
| Feature | Imperative | Declarative |
|---|---|---|
| Route Control | Full control at sign time | Optimized at execution |
| Latency | Higher (two API calls) | Lower (deferred calc) |
| Slippage | Fixed at quote time | Minimized at execution |
| Sandwich Protection | Standard | Enhanced |
| Use Case | Precise route requirements | Best execution priority |
connection.confirmTransaction()/order-status for completion// 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 provides infrastructure for trading prediction market outcome tokens.
Series (Collection)
└── Event (Occurrence)
└── Market (Outcome Trade)
// 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());
| Token | Mint Address |
|---|---|
| SOL (Wrapped) | So11111111111111111111111111111111111111112 |
| USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| USDT | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB |
| BONK | DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 |
| JUP | JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN |
| WIF | EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm |
Configure transaction priority:
// 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 };
}
}
Collect platform fees on swaps:
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());
For MEV protection and bundle submission:
// 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());
The DFlow Swap Orchestrator contract manages declarative swap execution:
Program ID: DF1ow3DqMj3HvTj8i8J9yM2hE9hCrLLXpdbaKZu4ZPnz
The Prediction Market Metadata API provides comprehensive access to prediction market information.
Base URL: https://api.prod.dflow.net
Series (Collection)
└── Event (Occurrence)
└── Market (Outcome Trade)
├── Yes Token (outcome mint)
└── No Token (outcome mint)
Returns a single event by its ticker with optional nested markets.
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.
Returns a paginated list of all events.
const events = await fetch(`${METADATA_API}/api/v1/events?limit=50&offset=0`, {
headers: { "x-api-key": API_KEY }
}).then(r => r.json());
Returns historical forecast percentile data.
Returns candlestick data from Kalshi.
Returns a single market by 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.
Lookup market by any mint (ledger or outcome mints).
const market = await fetch(
`${METADATA_API}/api/v1/market/by-mint/${outcomeMint}`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
Batch retrieve multiple markets (max 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());
Returns all yes_mint and no_mint pubkeys from all supported markets.
// 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());
Check if addresses are outcome mints (max 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());
Get orderbook by market 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 orderbook using mint address lookup.
Returns paginated trade history with filtering.
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 trades using mint address lookup.
Real-time milestone data from Kalshi.
const milestones = await fetch(
`${METADATA_API}/api/v1/milestones/TRUMP-2024`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
Returns series templates for recurring events.
Returns category tags for filtering.
Connect for real-time updates:
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);
};
| Status | Description |
|---|---|
initialized | Market created |
active | Trading enabled |
inactive | Trading paused |
closed | No more trading |
determined | Outcome known |
finalized | Payouts available |
DFlow provides several open-source tools on GitHub:
Repository: DFlowProtocol/solana-agent-kit
Toolkit enabling AI agents to connect to Solana protocols:
// 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.
Repository: DFlowProtocol/clearpools
Orca Whirlpools with support for flow segmentation:
// Extends Orca protocol with DFlow routing
import { ClearPools } from "@dflow/clearpools";
const pools = new ClearPools(connection);
await pools.initializePool(/* params */);
Repository: DFlowProtocol/dflow-amm-interface
Rust trait definitions for DFlow's AMM implementation. Use when building custom AMMs that integrate with DFlow routing.
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
executionMode and poll status
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).