name: dflow
description: Comprehensive guide for building Solana trading apps using DFlow's Swap API. Use when integrating quotes, routing, imperative/declarative swaps, or prediction markets.

DFlow - Next-Generation Solana Trading Infrastructure

Comprehensive guide for building trading applications on Solana using DFlow's Swap API. Enables token swaps with optimal routing, lower slippage, and access to both spot markets and prediction markets.

Overview

DFlow provides a suite of APIs for next-generation trading on Solana:
- 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
- Prediction Markets - Infrastructure for trading outcome tokens

Base URL

https://quote-api.dflow.net

Authentication

Most endpoints require an API key via the x-api-key header. Contact [email protected] to obtain credentials.

Quick Start

Imperative Swap (3 Steps)

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 (Unified - Recommended)

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;
}

API Reference

Order API Endpoints

GET /order

Returns a quote and optionally a transaction for spot or prediction market trades.

Response:

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

GET /order-status

Check status of async orders.

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

Imperative Swap Endpoints

GET /quote

Get a quote for an imperative swap.

POST /swap

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
}

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 an intent quote for a declarative swap.

POST /submit-intent

Submit a signed intent transaction for execution.

Request Body:

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

Token API Endpoints

GET /tokens

Returns list of supported token mints.

GET /tokens-with-decimals

Returns tokens with decimal information for proper amount scaling.

Venue API Endpoints

GET /venues

Returns list of supported DEX venues (Raydium, Orca, Phoenix, Lifinity, etc.).

Swap Modes Comparison

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

When to Use Declarative

• Prioritize best execution
• Lower slippage requirements
• Simple token swaps
• MEV protection is important

Execution Modes

Synchronous (Atomic)

• Single transaction execution
• All-or-nothing settlement
• Standard confirmation flow
• Use 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

// 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 };
    }
  }
}

Prediction Markets

DFlow provides infrastructure for trading prediction market outcome tokens.

Market Structure

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

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

Trading Prediction Markets

// 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());

Common Token Mints

Priority Fees

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
}

Error Handling

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 };
  }
}

Platform Fees

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());

Jito Integration

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());

DFlow Swap Orchestrator

The DFlow Swap Orchestrator contract manages declarative swap execution:

Program ID: DF1ow3DqMj3HvTj8i8J9yM2hE9hCrLLXpdbaKZu4ZPnz

Skill Structure

dflow/
├── SKILL.md                           # This file
├── resources/
│   ├── api-reference.md               # Complete API reference
│   ├── 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
├── templates/
│   └── swap-client.ts                 # Copy-paste starter
└── docs/
    ├── advanced-patterns.md           # Complex integrations
    └── troubleshooting.md             # Common issues

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

Resources

• DFlow Documentation
• API Keys
• Discord Community
• GitHub