Using AXIS

How AXIS works

AXIS consists of several parts: a smart contract that settles trades, an indexer and API that serve the orderbook, and apps that choose which orders to fill.

AXIS contract#

The AXIS contract is a smart contract on Stellar. It stores information about every open order, checks prices and settles each trade within one transaction: the trader pays each maker directly, and tokens from matched orders are passed back to the trader. The contract never holds your funds between transactions. It also never searches the book on its own: it only acts on the orders a trader passes in a transaction.

Indexer and the AXIS API#

The indexer watches the events the AXIS contract publishes, such as a new order, a trade or an update, and rebuilds the full orderbook from them. It also tracks each maker's balance and allowance, so it knows how much of every order can really be delivered. The indexer is an open-source library. To run your own copy, you connect it to a data source that delivers the contract's events and the makers' balances and allowances.

The AXIS API is a proprietary service run by AXIS and built on the indexer. It serves aggregated data for orderbook visualization, market depth, price candles and 24-hour statistics. It also provides basic routing that finds the best DEX orders to trade with for a given asset pair and trading amount. Apps talk to it over HTTP and WebSocket protocol.

Apps, wallets and bots#

Apps decide which orders to fill. When you trade, your app asks the AXIS API (or its own indexer) for the best orders, builds a transaction that lists them and asks your wallet to sign it. An app in this role is called a router. AXIS offers a ready-to-use routing that other apps can integrate right away, but anyone can build a custom implementation.

Off-chain matching, on-chain settlement#

Some on-chain orderbooks keep the book sorted inside the contract and search it for the best price on every trade. That costs computation and storage on every order and every trade.

AXIS splits the job in two:

• Matching happens off-chain. Routers find the best orders in the indexer's copy of the book, where searching is cheap and fast.
• Settlement happens on-chain. The contract receives a list of order IDs. For each one it checks that the order is still live, that its price satisfies the trader's limit and that its owner can pay. Then it moves the tokens.

This design was chosen because it combines the best from both worlds:

• Cheaper orders. The contract keeps no price index and no sorted price levels. A new order writes a single small storage entry.
• Open competition. Any app or bot can act as a router and look for better fills. The contract treats them all the same.
• Parallel trades. Trades on different assets touch different ledger entries, so the network can process them in parallel.
• Flexible execution. When exchanging at scale, a trader can easily skip dust orders and make sure that the order will be executed even if it requires a lot of liquidity.
• Safety stays on-chain. Whatever orders a router picks, the contract enforces each maker's price and the trader's limit.
• Tight security perimeter. It's way harder to find potential attack vectors in a small contract with simple execution engine.

The trade-off is that there is no on-chain price-time priority and the book can be crossed for a while. Features and limitations covers both.

Trade lifecycle#

Let's explore how it works with our good old friends, Alice and Bob.

1. A maker places a limit order. Alice offers to sell 100 XLM at 0.25 USDC each. The contract checks the price, the order size, her balance and her allowance, then stores the order on-chain and publishes a new event.
2. The indexer picks it up. The order appears in the book that apps see, together with how much of it Alice can actually deliver.
3. The taker's app asks for a quote. Bob wants to buy 100 XLM. His app asks the AXIS API, which answers with the IDs of the best orders for that amount and the expected matching price.
4. The taker signs a transaction. Bob signs a call to the AXIS contract that lists those order IDs and his limit price. The contract checks each order's price against Bob's limit and checks that Alice's balance and allowance cover the fill.
5. Tokens settle in the same transaction. Alice's 100 XLM moves to the AXIS contract, and Bob's 25 USDC moves straight to Alice's wallet. At the end of the call the contract forwards the 100 XLM to Bob in one transfer. The contract publishes a trade event for each fill, and the indexer updates the book.

Alice does not need to be online and has nothing to claim. Her USDC arrives in her wallet as part of Bob's transaction.

What your signature covers#

When you trade, your wallet asks you to sign one call to the AXIS contract: your assets, amount, limit price and the list of order IDs, plus an approval on the token you sell when your allowance needs topping up. You never sign payments. The contract pays to the makers out of your allowance, only for fills that respect your limit price. Because the signature does not depend on which orders end up filling, a signed trade stays valid even if the book changes before it lands. Security and trust covers all aspects of safety implications for this model.

When the book changes before your trade lands#

A few seconds usually pass between the quote and the moment your transaction is included in a ledger. Other traders may act in the meantime. The contract handles this order by order:

• An order is skipped if it was filled, canceled or expired before your transaction.
• An order that was partly filled gives you what is left of it.
• An order whose maker no longer has the balance or allowance for the fill, is skipped and left unchanged. The contract publishes a skip event so routers stop proposing it in the future.
• A payment to a maker that fails for another reason, for example because the maker cannot accept the tokens, fails the whole transaction, and no tokens are moved. The router can build an alternative quote for the execution.
• An order whose price changed and is now worse than your limit is skipped.

The rest of your trade goes through with fewer fills. What happens to the unfilled part depends on the order type. A limit order keeps it on the book so anybody else could trade with your order. A market order simply fills less, and the tokens you did not spend stay in your wallet. A Fill-or-Kill order or a swap fails as a whole when it cannot deliver what you asked for, and all transfers are discarded. Orders article explains each type.

Who runs what#

None of the off-chain services can move your tokens. The worst a faulty router or API can do is suggest poor orders or a poor price, but your wallet shows the price before you sign, so you can discard it. Developers can read more in Architecture and Design rationale.

Next steps#

• Orders explains limit orders, market orders, and updates.
• Allowances and your funds explains how the contract settles fills without holding your tokens between transactions.
• Markets and prices explains how markets open and what the oracle is used for.