ErgoDEXBetaExecution

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.

What you holdWho can take it backWhat the transaction must doNetwork fee
Limit order, DCA plan, smart order, stop or OCO order (limit order v3)The key of the address that placed it, and no one elseSpend the order box marked as a cancel (context variable 0 set to 0) and put its order token in no output; everything else in it is yours to send where you likePaid from the order’s ERG, or from an ERG box of yours: an order selling a token for ERG holds only the minimum ERG a box needs
Lithos orderThe key named in the order, and no one elseSpend the order box with that key’s signature. Your wallet must be able to sign an input of ErgoTree version 3Paid from the order’s ERG, or from your own: an order selling a token for ERG holds only 0.001 ERG
V3 positionWhoever holds the position’s key tokenSpend the position box together with the box holding the key, burn both units of the position token, and pay every token of the position and at least its ERG less 0.01 ERG to the key box’s address, one position per transaction. No configuration box is neededUp to 0.01 ERG of the position’s own ERG can pay it
V2 (Legacy) liquidityWhoever holds the LP tokensRedeem the LP tokens directly against the pool box, in one transaction of your ownFrom your own ERG
V2 liquidity (Crux)Whoever holds the LP tokensRedeem the LP tokens directly against the pool box, in one transaction of your own; an ERG pool keeps more than 2.4 ERG, so the last of it stays in the poolFrom your own ERG
Earlier orders: limit order v1 and v2, DCA vault v1 and v2The key of the address that placed itSpend the order box with that key’s signature; a limit order v1 must pay back to its own refund address, and a v2 limit order has a fee box that its owner takes back the same wayPaid from the order’s ERG or its fee box

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

FeePaid toWhenHow much
Network feeErgo minersEvery transaction you sign0.002 ERG by default, set in Settings
Pool feeThe pool’s liquidity providersEach swap through a poolSet by each pool, shown with the quote
SigmaUSD bank feeThe bank’s reserveEach mint or redemption, and bank parts of a route2%
Executor feeThe executor that fills: only ours for smart orders, DCA plans and stop and OCO orders; ours or Crux’s for limit ordersLimit orders, DCA plans, smart orders, stop and OCO orders, part by part, only on what fillsA fixed ERG amount written in the order and shown before you sign; the unused rest comes back if you cancel
Lithos executor feeThe executor that fills, which can be any executorLithos orders0.003 ERG, network fee included, shown with the quote before you sign
ErgoDEX fee——None

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.

—Alerts