Fill orders (EVM)

🚧
Order flow server
You must host a web server to receive order flow from DFlow and return quotes that meet best-execution requirements. When you reveal your bid, your URL will be displayed on DFlow Chain.
DFlow will release an open-source web server that adheres to the DFlow spec.

Fill orders

If you are the winning market maker of an auction, you have the exclusive right to fill orders (1) up to the auction's notional size (specified in USD) or (2) until the end of the auction's delivery period. Your right to execute orders ends when whichever of the above conditions is met first.

See Auction parameters for details on standardized auction parameters and Auction lifecycle to learn more about how an auction rolls over.

Step 1: Receive request and return quote

When users want to trade, they send RFQs (request-for-quotes) to the DFlow Swap API. The DFlow Swap API routes the /firmQuote request to the winning market maker. When quotes are requested, signed quotes are expected in return.

On EVM networks, DFlow uses 0x orders and they are settled using 0x Protocol smart contracts.

Firm quote request fields

You will receive a /firmQuote request in the following format:

Field	Type	Description
`sendToken`	string	Address of the ERC-20 token that the retail trader is sending.
`receiveToken`	string	Address of the ERC-20 token that the retail trader is receiving.
`sendQty`	string	Fixed send quantity.
`minFillQty`	string	Minimum allowed fill quantity as determined by the market best bid and offer.
`retailTrader`	string	Address of the retail trader's wallet.
`endorsement`	string	An endorsement by the order flow source's endorsement server.
`taker`	string	`taker` to use when constructing the 0x OTC order.
`chaindId`	string	`chainId` to use when constructing the 0x OTC order.
`verifyingContract`	string	`verifyingContract` to use when constructing the 0x OTC order.
`nonceBucket`	string	Nonce bucket to use when constructing the 0x OTC order. Formatted as a hex string.
`nonce`	string	Nonce to use when constructing the 0x OTC order. Formatted as a hex string.
`auctionId`	string	The auction ID identifying the auction the order matched.
`auctionEpoch`	string	The auction epoch for which the order belongs to.

Firm quote response fields

You must respond in the following format:

Field	Type	Description
`code`	number	This is the status code of the quote request. 0 means quote offered, 1 means quote refused. If the auction has the payment in lieu feature enabled and you refused or failed to give a valid quote (see below), DFlow Swap API will return to the order flow source a payment token giving the holder the right to retrieve a portion of the payments. See Payment flow for details on payment in lieu.
`fillQty`	string	Fixed fill quantity.
`maker`	string	This is your Ethereum wallet address. This is the signer of the 0x OTC order. This is the `maker` used to construct the 0x OTC order.
`expiryAndNonce`	string	`expiryAndNonce` used to construct the 0x OTC order. Formatted as a hex string.
`otcOrderSignature`	string	This is your signature of the 0x OTC order.
`quoteId`	string	An ID identifying the quote request.

👍
Best execution guidelines
A valid quote must follow the below guidelines:

You must return a quote within 3 seconds

Quote must be equal to or better than the minFillQty

More criteria will be added.

Step 2: Send order

EVM transactions signed by retail traders are sent back to you for last-look. You are responsible for broadcasting the transaction on EVM networks.

Send transaction request fields

You will receive a /sendTransaction request in the following format:

Field	Type	Description
`tx`	string	Ethereum transaction signed by the retail trader.
`quoteId`	string	An ID identifying the quote request.

Send transaction response fields

Your response to the /sendTransaction request must be in the following format:

Field	Type	Description
`code`	number	This is the status code of the sendTransaction request. 0 means transaction was sent to the network, 1 means transaction was not sent to the network.
`txHash`	string	Ethereum transaction hash.

📘
Time of payments
Payment happens at the time when DFlow Swap API makes the /sendTransaction request to your server. Therefore, you are incentivized to provide reliable quotes and ensure transactions are successfully settled on the specified EVM network.

Provide indicative quotes

Step 1: Receive request and return quote

To indicate current token pricing for DFlow Swap API and trading interfaces, you must provide pricing for orders that match your won auction(s). You will only need to provide pricing for auctions where you are the current winner.

Firm quote request fields

You will receive an /indicativeQuote request in the following format:

Field	Type	Description
`sendToken`	string	Address of the ERC-20 token that the retail trader is sending.
`receiveToken`	string	Address of the ERC-20 token that the retail trader is receiving.
`minFillPrice`	string	Minimum allowed fill price. Specified as token units sent to retail trader per token received from retail trader.
`auctionId`	string	The auction ID identifying the auction the order matched.
`auctionEpoch`	string	The auction epoch for which the order belongs to.

Indicative quote response fields

Your response to the /indicativeQuote request must be in the following format:

Field	Type	Description
`fillPrice`	string	Token units sent to retail trader per token received from retail trader. Must be equal to or better than the minFillPrice.