How orders are routed and filled
Updated
What happens between pressing the button and seeing the result: how ErgoDEX finds a route, when you sign, who fills orders and what each fee pays for.
Swaps and Smart Route
When you enter an amount, our servers read the current pool boxes on the chain and look for the best way to fill the swap across the available sources: V2 (Legacy) and V3 pools, Lithos pools, open Machina orders and the SigmaUSD bank. Every route is one transaction, in one of two shapes:
- Direct: one source.
- Split: several sources, which can include the SigmaUSD bank. It completes as a whole or not at all.
If no single transaction can fill the swap, ErgoDEX shows no route.
Every swap transaction states the least you accept: the quote minus your slippage (0.5% by default, set in Settings). If the pools have moved past that when the transaction reaches a block, the transaction is invalid and nothing leaves your wallet. Quotes refresh often and expire within seconds; if one expires before you sign, ErgoDEX asks you to review a fresh one.
“Best route” means the most you would receive by our estimate at the moment of the quote, after the fees of every pool, the SigmaUSD bank and the V3 protocol fee. The network fee is left out of the comparison: every route is one transaction and pays the same one. When a swap through a Lithos pool is placed as a Lithos order, its 0.003 ERG executor fee is not part of the comparison either. “Best route” is not a promise of best execution or of the best price available anywhere.
Smart orders
Some large ERG trades do better spread over sources that cannot share one transaction. ErgoDEX may then offer a smart order, but only when, after its executor fee, it is expected to give at least 0.3% more than the one-transaction route: you sign once to place an order, and our executor fills it one source per transaction, usually within a block or two. What it buys collects in the order and comes to you in one payout. The guaranteed amount is the order’s limit; whatever is unfilled can be sent back to you once the expiry shown has passed (see Expiry).
Limit orders
A limit order is a box on the chain that holds what you sell. Our executor fills it, at once or in parts, whenever the pools give at least your price. Each fill pays the executor fee for that part only. What the order buys stays in it and comes to your wallet in one payout once the order is filled.
When our executor fills at a better price than your limit, the difference goes into your order: the executor is paid only by its fee. Limit orders also name the Crux executor as a backup that may fill them.
You choose an expiry from one hour to fourteen days, or none: the order then waits until it fills or you cancel it, for at most three years. An order that sells a token also holds 0.0011 ERG as an expiry reserve. The reserve is yours: it comes back to you when the order fills or you cancel it. After an order expires, our executor normally sends it back to your address. The order pays only its share of that transaction’s network fee, never more than 0.0011 ERG; everything else comes back with it, and our executor keeps nothing. When an order’s own ERG cannot pay its share, our executor pays the rest itself, up to a fixed amount per transaction. That is a service, not a guarantee: while our executor is down, an expired order waits until you cancel it or someone else sends it back (see Expiry).
DCA plans
A DCA plan is one order that holds the whole budget. Our executor sells it in parts: the first part right away, then at most one part per interval you chose; a part that could not run is spread over the periods left. Every part goes through Smart Route.
A part fills only at a price within the limit you set (by default 25% worse than the price at the start), and the contract enforces that limit. The schedule itself is kept by our executor, not by the contract.
Everything bought stays in the plan and comes to you in one payout at the end, or with the rest when you cancel.
Lithos orders
Some wallets cannot sign a transaction that spends a Lithos pool directly. ErgoDEX then places a Lithos order instead: a box that any executor can fill against the pool, usually in the next block, for a fixed executor fee of 0.003 ERG. The quote shows that fee next to the pool fee before you sign.
Partial fills, cancelling and downtime
- An order can fill in several parts. Our executor fills only when the fee for that part covers the cost of the transaction, so a very small order or remainder can wait until you cancel it.
- You can cancel an order at any time from Swap or Portfolio and sign the cancel in your wallet. It returns the unsold part, everything bought so far and the unused executor fee. Nautilus cannot sign the cancel of a Lithos order; ErgoDEX cancels those through ErgoPay.
- If our executor is down, nothing is filled and nothing is lost: the order waits on the chain with your funds in it, and you can cancel it.
- Orders placed with earlier contract versions can always be cancelled, and are still filled where their contract allows.
If ErgoDEX is unavailable
Your orders and positions do not depend on this website. Each one is a box on the Ergo chain, and a transaction that takes it back is valid whoever builds it, as long as it follows the box’s contract and carries the right signature. To build one without ErgoDEX you need a wallet or tool that can spend a contract box, the box’s ID (it is an output of the transaction that placed the order, in your wallet’s history) and a little ERG for the network fee. The template hash of every contract below, by which a node or an explorer finds its boxes, is on Contracts.
Expiry moves nothing by itself. Once a limit order’s expiry height has passed, anyone may send the transaction that returns it to its owner’s address, with no signature. For a limit order v3, the contract lets at most 0.0011 ERG of the order’s own ERG pay the network fee of that refund. An order that sells a token carries 0.0011 ERG for this, its expiry reserve, and the reserve comes back to its owner when the order fills or is cancelled. Our executor normally sends the refund. Each order in it pays only its share of the network fee the transaction actually pays; everything else goes back to the owner, and our executor keeps nothing. When an order cannot pay its share, as an older order selling a token cannot, since it holds only the minimum ERG a box needs, our executor pays the rest of the network fee itself, up to 0.003 ERG per refund transaction. That is a service, not a guarantee: while our executor is down, an expired order stays on the chain until you cancel it or someone else sends the refund. Lithos orders, DCA vaults and V3 positions have no expiry.
If our executor is down, smart orders, DCA plans and stop and OCO orders are not filled, because they name only our executor; limit orders can still be filled by Crux’s executor, and Lithos orders by any executor.
Fees
An order box also carries a little ERG, because every box on Ergo must hold a minimum. It comes back with the payout or when you cancel.