Trade Quotes

This endpoint provides quotes for different order types: market, limit, and twap (Time-Weighted Average Price). Quotes include pricing information, expected slippage or price-impact, and other trade details.

Request URL

https://ddp.definitive.fi/v1/trade/quote

Request Body

The request body varies based on the order type:

Base Parameters (All Order Types)

{
  "type": "market" | "limit" | "twap",
  "chain": "ethereum" | "optimism" | "arbitrum" | "avalanche" | "polygon" | "base" | "solana" | "blast",
  "from": "0x…",                // Asset address to sell/buy from
  "to": "0x…",                  // Asset address to buy/sell to
  "qty": "1000.00",             // Amount to trade
  "orderSide"?: "buy" | "sell", // Optional configuration for UI only
 
  // Execution-protection fields (use exactly one, per order type):
  // ───────────────────────────────────────────────────────────────────────────
  // Market orders: only slippageTolerance applies
  "slippageTolerance"?: "0.01",   // e.g. 1% = 0.01
 
  // TWAP orders: only maxPriceImpact applies
  "maxPriceImpact"?: "0.05",      // e.g. 5% = 0.05
 
  // Limit orders: neither slippageTolerance nor maxPriceImpact applies,
  // you are protected by your limitPrice or limitNotional* fields
}

Market Order

For market orders, you may only set slippageTolerance, maxPriceImpact will be ignored.

{
  "type": "market",
  "slippageTolerance": "0.01",  // required, max % less than quoted out-amount
  // Base parameters...
}

Limit Order

For limit orders, do not set slippageTolerance or maxPriceImpact. Instead choose one of:

// Option A: cross-price limit
{
  "type": "limit",
  "limitPrice": "0.5",
  // Base parameters...
}
 
// Option B: notional limit
{
  "type": "limit",
  "limitNotionalPrice": "2000.00", // price in notional asset
  "limitNotionalAsset": "0x…",     // must pair with limitNotionalPrice
  // Base parameters...
}

TWAP Order

For TWAP orders, you may only set maxPriceImpact, slippageTolerance will be ignored.

{
  "type": "twap",
  "durationSeconds": 3600,         // total execution time
  "targetTWAPBuckets"?: 6,         // number of slices
  "maxPriceImpact": "0.05"         // max % price-impact per bucket
  // Base parameters...
}

Response

{
  quote: {
    from: "0xA12B…234D",
    to:   "0xF987…765D",
    chain: "base",
    qty: "1000.00",
    orderSide?: "sell",
    slippageTolerance?: "0.01",   // only for market
    maxPriceImpact?: "0.05",      // only for twap
    quoteId: "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    quotedAmountOut: "0.050123",
    quotedPriceImpact: "0.025",
    type: "market"                // "market" | "limit" | "twap"
    // + limitPrice or limitNotional* if type==="limit"
    // + durationSeconds & targetTWAPBuckets if type==="twap"
  },
  metadata: {
    toNotional: "1000.00",
    fromNotional: "1005.25",
    estimatedPriceImpact: "0.025",
    estimatedFee: "0.75",
    estimatedFeeNotional: "0.75",
    buyAmount: "0.050123",
    sellAmount: "1000.00",
    sources: { Uniswap_V3: "0.8", SushiSwap: "0.2" },
    expectedSlippage: "0.008",
    minAmountOut: "0.04962",
    minAmountOutNotional: "990",
    price: "19950.123",
    isMarketable: true
  }
}

Example

const quoteRequest = {
  type: "market",
  chain: "base",
  from: "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D", // EURC
  to: "0xF98765C43210D78E90AB56CD12EF34A908BC765D", // cbBTC
  qty: "1000.00",
  orderSide: "sell",
  slippageTolerance: "0.01",
};
 
const json = await AuthHelpers.signAndSend({
  path: "/v1/trade/quote",
  method: "POST",
  body: quoteRequest,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);

Next Steps

After receiving a quote, the next step is typically to submit the order if you're satisfied with the quote details.