Using AXIS

Trading with the AXIS

A step-by-step guide to the AXIS trading interface on Stellar Testnet: set up a wallet, place orders, swap tokens and manage your orders.

The Demo AXIS app currently runs on the Stellar Testnet, where tokens have no real value, so it is safe to experiment.

Before you start#

You need:

• A Stellar wallet. The app supports Freighter, Albedo and xBull wallets. Make sure your wallet uses the Stellar Testnet.
• A funded Testnet account. If your account is new, the app shows "Account not yet funded on Testnet" with a "Fund via Friendbot" button. Click it to receive free test XLM.
• Trustlines For the assets you want to receive, see below.

Add trustlines#

To hold USDC, EURC or CETES tokens, your account needs a trustline for each. XLM needs none. Add them in your wallet before you trade, using the codes and issuers below, or let the AXIS app create them: when the asset you would receive has no trustline, the trade and swap forms show a "trustline" link that creates it with one transaction signed in your wallet. Each trustline locks 0.5 XLM of reserve, which you get back when you remove it.

Without a trustline, or with a trustline that has no room left under its limit, an order that would pay you in that asset fails with "You cannot receive the bought asset". The trade and swap forms warn you before you submit, and offer to create a missing trustline or raise the limit of a full one. A swap into that asset fails with a token error. With trustlines in place, you can get test USDC, EURC or CETES from a Testnet facet (https://faucet.circle.com/) or by swapping test XLM.

Connect your wallet#

1. Open dex-demo.axis.markets. On your first visit a welcome dialog lists the supported assets. Click "Let's roll!".
2. Click "Connect wallet" in the top bar.
3. Choose Freighter, Albedo or xBull, and approve the connection in your wallet.

The button now shows your shortened address. Click it to disconnect.

Pick a market#

Click the market name next to the AXIS logo to open the market list, then search for a market and click it. Markets show as BASE/QUOTE, for example XLM/USDC: prices are in USDC per XLM and amounts in XLM.

Read the trading screen#

The orderbook and depth chart count only the backed part of each order.

Place a limit order#

1. In the trade panel, choose the buy or sell tab, for example "Buy XLM" or "Sell XLM" on the XLM/USDC market.
2. Select "Limit".
3. Enter the price in the quote asset, or click a row in the orderbook to copy its price.
4. Enter the amount in the base asset. You can also click 25%, 50%, 75% or 100% to use part of your available balance, or type a Total in the quote asset.
5. Pick when the order expires in the Expires setting: Never (the default), 1 hour, 1 day, 7 days, 30 days, a custom date at least 5 minutes ahead, or Fill-or-Kill. The app keeps your choice for the next orders.
6. Check the Order Value and click the "Buy XLM" or "Sell XLM" button.
7. Review the transaction in your wallet and sign it.

A notification shows the result, for example "Bought 16.7 XLM (68% executed), new order created". The part that filled right away is already in your wallet. Any unfilled remainder stays on the book as an open order until it fills, you cancel it or it expires.

With Fill-or-Kill, the order fills in full at your price or better, or fails, and nothing stays on the book. The form warns "Not enough liquidity at this price to fill the whole amount" when the current book cannot fill it. See Fill-or-Kill.

The Network Fee line in the form shows the most the transaction can cost, worked out by simulating your order once you stop typing. It includes the storage rent of a new order. Your wallet also shows a maximum before you sign, which can be higher than the form's figure. The network charges the same either way. To change an open order later, edit it.

Place a market order#

1. Choose "Buy XLM" or "Sell XLM" and select "Market". The price field shows the current mid price and cannot be edited.
2. Enter the amount in the base asset.
3. Click the buy or sell button and sign in your wallet.

The app asks the AXIS API for the orders that cover your amount and uses the worst price among them as your limit. If the book cannot cover the whole amount, the app stops with "Not enough liquidity for a market order" before you sign. Nothing stays on the orderbook. If the book changes before your transaction lands, you may get less than the full amount, and the rest stays in your wallet. See Market orders.

Swap tokens#

1. Click "Swap" in the top bar.
2. Choose the asset you pay and the asset you receive. The ⇅ button flips them.
3. Enter an amount in one of the two fields:
   • In "You pay" for an exact input. You pay this amount and receive at least the amount quoted when you click "Swap". "Max" enters your whole available balance.
   • In "You receive" for an exact output. You receive exactly this amount and pay at most the estimate.
4. Check the Rate and the Route, for example XLM → USDC → EURC.
5. Set the Slippage: 0.1%, 0.5% (the default) or 1%, or type your own value from 0.01% to 50%. The app remembers it in your browser and warns above 5%.
6. Check "Minimum received" for an exact input, or "Maximum paid" for an exact output.
7. Click "Swap" and sign in your wallet.

When you click "Swap", the app gets a fresh quote and accepts a result worse by at most your slippage: at least its output minus the slippage for an exact input, at most its cost plus the slippage for an exact output. If the book moves further before your transaction lands, the swap fails with "Order cannot be executed in full" and nothing moves. See Swaps across several markets.

One signature per action#

Each order or swap needs one wallet signature. If your allowance on the token you sell is too small or about to expire, the app adds the approval to the same transaction. See How the AXIS app grants it.

Open orders#

The OPEN ORDERS tab at the bottom lists your orders with SIDE, PAIR, TYPE, PRICE, AMOUNT, FILLED, EXPIRES and CREATED. The "This market only" box, checked by default, limits the list to the current market. Click an order to edit it.

Two tags can appear next to the pair:

• pending means the order was just created and the indexer has not confirmed it yet.
• N% backed means your balance or allowance in the token you sell no longer covers the whole order. Hover over it to see your balance, your allowance and the allowance's expiry ledger. Fills larger than the backed part are skipped.

To restore full backing, add tokens to your wallet. If the allowance is short or expired, place a new order selling that token. Its approval covers all your open orders selling the token. See Order backing.

The app also notifies you when one of your orders is partially filled, filled or expires.

Edit an order#

1. Click the order in the OPEN ORDERS list.
2. Change the price, the amount or the expiration. "Keep" leaves the current expiration as it is.
3. Click "Save changes" and sign in your wallet.

The order keeps its ID, and the update costs less than a new order (see Updating an order). Only the fields you changed are sent. If the new amount needs more allowance, the same transaction adds an approval, and if it needs less, the allowance shrinks to what your open orders need. An edit works like a new order: your balance must cover the new amount and the market must have a fresh oracle price. While trading is frozen you can only cancel orders.

Cancel orders#

• One order: click ✕ at the end of its row and sign.
• All orders: click "Cancel All". It cancels every open order on the current market, or on all markets when "This market only" is unchecked. The app sends one transaction per 90 orders, so you may need to sign more than once.

Canceling also lowers your allowance on the token you sold to what your remaining open orders need, and revokes it once none are left. See How the AXIS app grants it.

Manage allowances#

Click "Allowances" in the top bar to see each token you allowed the AXIS contract to move, with the amount, the expiry date and the number of your open orders it backs.

• One token: click "Revoke" in its row.
• All tokens: click "Revoke all".

The dialog offers to cancel the open orders selling the token in the same transaction, which is on by default. Keep it on: revoked alone, those orders stay on the book unbacked and their fills are skipped. Revoking works even while trading is frozen. See Revoking an allowance.

Order history#

The ORDER HISTORY tab lists orders that are no longer open, with their status: FILLED, CANCELED or EXPIRED.

Common error messages#

Errors appear in the form and in a notification, such as "Buy failed: Insufficient balance".

Developers can find every contract error code in Errors.