Skip to content

Submit Orders

This endpoint submits a trade order for execution. You must first obtain a quote using the /v1/trade/quote endpoint and then submit that quote through this endpoint.

Request URL

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

Request Body

The request body should contain the quote object received from the /v1/trade/quote endpoint. This is the complete quote object from the response's quote field, including the quoteId which is required for order submission.

{
  "from": "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D", // From token address
  "to": "0xF98765C43210D78E90AB56CD12EF34A908BC765D", // To token address
  "chain": "base",
  "qty": "1000.00",
  "orderSide": "sell",
  "maxPriceImpact": "0.05",
  "slippageTolerance": "0.01",
  "quoteId": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890", // Important! This links the order to the quote
  "quotedAmountOut": "0.050123",
  "quotedPriceImpact": "0.025",
  "type": "market" // Can also be "limit" or "twap" with respective fields
}

If submitting a limit order, include the limit-specific fields:

{
  // Base fields...
  "type": "limit",
  "limitPrice": "0.5",
  "limitNotionalPrice": "2000.00", // Optional
  "limitNotionalAsset": "0x..." // Optional
}

If submitting a TWAP order, include the TWAP-specific fields:

{
  // Base fields...
  "type": "twap",
  "durationSeconds": 3600,
  "targetTWAPBuckets": 6 // Optional
}

Response

{
  "orderId": "e12f34a5-b678-90cd-12ef-3456abcd7890",
  "vaultIds": ["c12d34e5-f678-90ab-1234-ef567890bcda"],
  "chains": ["base"],
  "status": "ORDER_STATUS_ACCEPTED",
  "from": "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D",
  "fromAddress": "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D",
  "to": "0xF98765C43210D78E90AB56CD12EF34A908BC765D",
  "toAddress": "0xF98765C43210D78E90AB56CD12EF34A908BC765D",
  "size": 1000,
  "filledSize": 0,
  "orderType": "ORDER_TYPE_MARKET", // Or "ORDER_TYPE_LIMIT" or "ORDER_TYPE_TWAP"
  "createdAt": "2025-03-07T18:04:42.000Z",
  "startsAt": "2025-03-07T18:04:42.000Z",
  "acceptedAt": "2025-03-07T18:04:42.000Z",
  "fills": [],
  "pendingCancel": false,
  "paused": false,
  "maxPriceImpact": 0.05,
  "slippageTolerance": 0.01,
  "side": "sell"
}

Example

// First get a quote
const quoteRequest = {
  type: "market",
  chain: "base",
  from: "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D", // EURC
  to: "0xF98765C43210D78E90AB56CD12EF34A908BC765D", // cbBTC
  qty: "1000.00",
  orderSide: "sell",
  slippageTolerance: "0.01",
  maxPriceImpact: "0.05"
};
 
const quoteResponse = await AuthHelpers.signAndSend({
  path: "/v1/trade/quote",
  method: "POST",
  body: quoteRequest,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Then submit the quote to create an order
const orderResponse = await AuthHelpers.signAndSend({
  path: "/v1/trade",
  method: "POST",
  body: quoteResponse.quote,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(orderResponse);

Next Steps

After submitting an order, you can: