Swap
Place a swap, follow it through the queue, and read each outcome it can end in.
A swap is the sealed order that trades now. When its turn comes it crosses the opposite resting orders in the book at the pool's mid, then sweeps the pool's curve for what is left, inside your limit. Whatever it does not fill stays in your sealed balance: a swap never rests. The mechanism is told in Sealed orders.
You need a sealed balance in the market that covers the order: see Deposit and withdraw. The SDK samples assume hadal, connection, payer, market and key as set up in the Quickstart.
The order
| Choice | Seen by | Meaning |
|---|---|---|
Market | the chain | The pair. Its base token is what you buy or sell, its quote token is what you pay or receive. |
Side | you | Buy or sell the base token. |
Size | you | How much of the base token. |
Limit | you | The worst price you accept, in quote per base. A buy pays no more than it, a sell accepts no less. |
Side, size and limit are encrypted in your wallet before the order leaves it, together with your wallet's address: the cluster checks that the order was sealed by the wallet that placed it. The chain shows that your wallet placed a swap in this market, and nothing about it.
The balance must cover the order's worst case before anything trades. A sell needs its size in the base token. A buy needs its size at the limit in the quote token, plus 0.3% of that for the fee. An order the balance does not cover is void.
The limit does two things. The order crosses the book only while the pool's mid is inside it. And the remainder sweeps the curve only if the average price of that sweep, fee included, is inside it: the sweep takes all of the remainder or none of it.
The estimate
The ticket has a row that begins Estimate at the and names the time of the market's last sounding in UTC. Its figure is your size times that sounding's price. Under it is the fee at its highest, Fee, at most 0.30%, which is that estimate times the sweep rate.
The estimate is built from the last sounding because that is the newest price the chain has. The pool's reserves and the book are sealed, so nobody can quote the fill ahead of it. The order fills at the pool's mid and on its curve as they stand when the order is processed, and the receipt holds the real figures. The ticket fills the limit in from the same sounding, 0.5% above it for a buy and 0.5% below it for a sell, until you type your own.
With the SDK, the last sounding's price is in GET /v1/markets/:market. The rates are in Fees.
Place the swap
Pick the market
Open Trade and choose the pair in the market picker above the chart.
Fill the ticket
Keep Swap selected. Choose Buy or Sell, enter the Size in the base token, and set the limit: Limit: pay no more than for a buy, Limit: accept no less than for a sell. The ticket shows your sealed balances of both tokens. Max fills in the size your balance covers at the limit, the fee included, and a larger size is marked with what the balance covers.
Press Swap and sign
Press Swap and sign once. The ticket follows the order: Sealing in your wallet, Waiting for your signature, In the queue with its position, The cluster is computing, then the result.
If the ticket shows Unlock, unlock first. If it shows Deposit, your balance in this market is empty: the button leads to the deposit form.
Placing is one transaction. It creates the order's account, for which your wallet pays the rent, and gives the order the next place in the market's queue. It queues no computation and moves no balance.
The order's address is derived from the market's next queue sequence at the moment the SDK builds the instruction. If another order takes that sequence before yours is confirmed, your transaction is refused: build the action again and send it.
The program refuses the transaction with EmptyBalance when nothing has ever landed in your balance in this market, and with MarketNotReady when the market's pool has not opened.
The queue
Orders in a market are processed one at a time, in the order they were placed. While yours waits, its status is pending.
The ticket shows In the queue with position N. The order is also listed under Open orders with the same status and a Cancel button, and the bar shows how many of your orders are in the queue.
Cancel while pending
A pending order can be cancelled by its owner. It closes in the cancelling transaction itself, with no computation: nothing was taken from the balance, and the order has no receipt.
Press Cancel on the order's row under Open orders and sign. The app confirms Order cancelled.
While the market has a computation in flight, the cancel of a pending order is refused with Busy, because the order may be the one being computed. Send it again a moment later.
Outcomes
When the order has been processed its status is closed and its receipt says how it ended. A swap ends in one of four ways.
| Outcome | Receipt | What happened and what to do |
|---|---|---|
Filled | filled equals the size | The whole size traded: crossed is what met resting orders at the mid, swept is what traded on the curve. Your balance holds the result. |
Partly filled | filled below the size, swept 0 | Part crossed the book at the mid. The curve could not fill the remainder inside your limit, so the remainder stayed in your balance. Place a new swap for it, with a wider limit if you want it filled now. |
Returned unfilled | ok true, filled 0 | The limit was not met: the mid was outside it, or nothing crossed and the sweep was outside it. Nothing moved. Place it again with another limit, or as a dark order that waits at your price. |
Void | ok false | The balance did not cover the worst case of the order, or an amount in it does not fit the integer range. Nothing moved. Deposit, or place a smaller order. |
The integer ranges are in Limits and measured figures.
The ticket shows the result under the button: Filled, Partly filled or Returned unfilled, with the rows Filled (amount and average price), Crossed at the mid, Swept the curve, Returned to your balance and Fee. A void order shows Order void and the reason. The receipt then stays under Receipts on Trade and on Portfolio.
Orders closed without a computation
So that no order can hold a market's queue, the order at its head is closed without being computed in these cases. Nothing moves, the order's status becomes closed, and it has no receipt.
| Case | What to do |
|---|---|
Cancelled | You cancelled it while it was pending. |
Balance busy | When its turn came, your balance in the market was held by another computation: a deposit, a withdrawal, a collect, a liquidity change or a deal still in flight. Wait for that to land, then place the order again. |
Expiry passed | A dark order whose expiry passed before its turn. A swap has no expiry. |
Book full | A dark order that found every place in the book taken. |
The chain shows that the order was returned and which case it was, as the reason of the OrderReturned event: see the program reference.
The ticket ends in Not placed, the order leaves Open orders, and no row is added to Receipts.
The receipt of a swap
| Field | Unit | Meaning for a swap |
|---|---|---|
ok | boolean | False when the order was void. |
filled | base atoms | What traded: crossed plus swept. |
quote | quote atoms | What the fill paid (a buy) or received (a sell). The sweep fee is inside this figure. The cross fee is not. |
crossed | base atoms | The part that met resting orders, at the pool's mid. |
swept | base atoms | The part that traded on the curve. |
rested | base atoms | Always 0 for a swap. |
fee | quote atoms | The cross fee on what crossed plus the sweep fee on what swept. |
The average price is quote divided by filled: priceOf(receipt.quote, receipt.filled) gives it in the unit of a limit. A buy takes quote plus the cross fee out of your quote balance and adds filled to your base balance. A sell takes filled out of your base balance and adds quote less the cross fee to your quote balance. Read your receipts covers the receipt in full.
When a computation expires
Processing an order is a computation on the cluster. If the cluster does not take it up within 180 slots, the computation expires and nothing has changed: no balance moved and the order has no receipt. The order is still pending at the head of the queue, and the market's book and your balance stay held by the expired computation until each is released, after the release window.
What happens next depends on the order of the releases. When your balance has been released (reclaim) by the time the order is run again, the order is processed as if for the first time. When only the market has been released, the order finds your balance still held and is closed without a computation, as a balance busy order: place it again.
The order stays under Open orders as In the queue while it is pending, and leaves the list if it is closed. There is nothing to sign again unless you place a new order.
The lifecycle of a computation is told in Arcium and the trust model, and which release follows which expired computation in Release instructions.