Developers / JavaScript client

Axis, markets and accounts

Reference for the stateful Axis, AxisMarket and AxisAccount classes, which follow the live DEX state and trade with automatic allowances.

These classes keep the contract state, the markets and a trader's open orders in memory. The AXIS API pushes changes over WebSocket, with REST polling while the push connection is down. Transactions go through an internal AxisContractClient, so everything on that page about simulation, footprints and errors applies here too.

Axis#

import {Axis} from '@axis-markets/client'
import {Networks} from '@stellar/stellar-sdk'

const axis = new Axis({
    apiUrl: 'https://demo-api.axis.markets',
    rpcUrl: 'https://soroban-testnet.stellar.org',
    networkPassphrase: Networks.TESTNET
})
await axis.connect() // the contract address comes from the AXIS API
axis.on('frozen', frozen => console.log(frozen ? 'trading suspended' : 'trading resumed'))

Options#

Properties#

Methods#

Events#

on(event, listener) returns an unsubscribe function. once and off work as usual. A listener that throws is logged and does not break the others.

AxisMarket#

Get a market with axis.getMarket(x, y) or iterate axis.markets.values(). Assets are token contract addresses in the contract's canonical order, which compares encoded addresses rather than strings. For XLM and USDC on Testnet, base is USDC and quote is XLM.

Market properties#

Market data#

getDepth, subscribeDepth and subscribeCandles take a base asset that sets the orientation of prices (market.base by default). Prices are then quoted in counter(base) per base.

const XLM = 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC'
const USDC = 'CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA'

const market = axis.getMarket(XLM, USDC)

// XLM priced in USDC, in levels of 0.001 USDC
const depth = await market.getDepth({base: XLM, step: '0.001', limit: 20})
console.log('best bid', depth.bestBid, 'best ask', depth.bestAsk)

const stopDepth = market.subscribeDepth({base: XLM, step: '0.001'}, update => console.log(update.bids[0], update.asks[0]))
const stopTrades = market.subscribeTrades((trades, snapshot) => console.log(snapshot ? 'recent' : 'new', trades.length))
const stopCandles = market.subscribeCandles({base: XLM, resolution: '15m'}, (candles, snapshot) => console.log(candles.length, snapshot))

Payload formats are documented in the REST API and the WebSocket API.

Oracle upkeep#

signer defaults to the signer option of Axis. Both calls are permissionless. See Running a keeper.

AxisAccount#

const account = axis.account(address, {signTransaction})
await account.ready

signTransaction is required to trade and to estimate fees. Without it the account still tracks orders and balances.

Account state#

An AccountBacking is {asset, balance, allowance, liveUntil, authorized, budget, updated, skipped, pending}. budget is min(balance, allowance), or 0 when the account is not authorized for the token or the allowance has expired. skipped is the time of the last skip event of an order selling the token, and pending means a reload confirming the latest change is still due. Times are UNIX milliseconds.

AccountOrder fields:

Placing orders#

sell(params) sells a fixed amount, buy(params) buys a fixed amount. Both call the contract's trade.

The result is {sold, bought, orderId, order, approve}:

// limit buy: up to 50 XLM, paying at most 0.24 USDC per XLM, stays on the book for one day
const {orderId} = await account.buy({
    selling: USDC,
    buying: XLM,
    amount: 500_000_000n,
    price: 240_000_000_000_000_000n,
    expires: Math.floor(Date.now() / 1000) + 86_400
})

The remainder of a buy is stored as an order selling selling (see Order).

Without orders, a limit order lists the orders of a direct quote with the order's limit as maxPrice: every backed order priced within the limit, best first, up to 20, even when they cover only part of amount. The contract fills them and stores the remainder as an order. Pass orders yourself to choose the crossing, or orders: [] to place the whole order on the book without crossing anything.

estimateSell(params) and estimateBuy(params) take the same parameters, look up the same crossing and plan the same approval, then only simulate the trade. Nothing is signed or submitted. They return {fee, inclusionFee, resourceFee, sold, bought, orderId}, with the fees in stroops. fee is the maximum network fee of the transaction, the inclusion fee bid plus the resource fee, which includes the rent of a new order. Show it next to the order form.

const {fee} = await account.estimateSell({selling: XLM, buying: USDC, amount: 1_000_000_000n, price: 25n * 10n ** 16n})
console.log(`Network fee: up to ${Number(fee) / 10_000_000} XLM`)

Market orders#

Without price the trade is a market order:

1. The account requests a direct quote for amount (quoteSell for sell, quoteBuy for buy, single hop).
2. The limit is the quote's worstPrice, the highest maker price crossed. A buy uses it as is, a sell uses invertPrice(worstPrice). Every quoted order passes the price check.
3. The kind defaults to Fill: what cannot be filled is dropped and nothing stays on the book. Pass kind: OrderKind.FillOrKill to require a full fill.

// buy 10 XLM with USDC at the best prices available
const {sold, bought} = await account.buy({selling: USDC, buying: XLM, amount: 100_000_000n})

A quote succeeds only when the book can fill the whole amount. A market order larger than the available liquidity therefore throws Not enough liquidity for a market order before anything is signed. Split it or lower the amount.

Updating and canceling#

All three send one transaction per 90 orders. When an update grows the amount on offer in a token, the account plans an approval for the growth and sends it with the first batch. An order whose expiration has passed needs a new expires (0 or in the future) to be revived.

Amounts are absolute, so a fill that lands between signing and execution is not counted against the new amount. To cut exposure whatever is in flight, cancel the order or lower the allowance (see Absolute amounts and fills in flight).

await account.update([{id: orderId, price: 260_000_000_000_000_000n}]) // reprice, keep the amount
await account.update([{id: orderId, amount: 500_000_000n, expires: 0}]) // resize, no expiration
await account.cancelAll({market: axis.getMarket(XLM, USDC)})

Crossfills#

crossfill(takerOrderId, orders) fills an existing order against cheaper orders with this account as the caller, which receives the surplus. Without orders it finds them with a direct quote for the taker order's full amount, which lists nothing when the book cannot fill that amount. The result is {sold, bought, surplus}: what the taker order's owner paid, what the makers delivered, and the part of it paid to this account, all zeros when nothing matched or the taker order was skipped. The account needs no funds but must be able to receive the taker order's buying asset. See Crossfill and Bots and arbitrage.

Swaps#

swap({selling, buying, amount, direction, slippage}) trades along the best route of the AXIS API, up to several hops:

1. It requests a quote: quoteSell for TradeDirection.Sell (the default, amount is the exact input) or quoteBuy for TradeDirection.Buy (amount is the exact output).
2. It takes the best route and turns each hop into a TradeStep (asset = the hop's buying, orders = its IDs).
3. It sets the bounds. Sell: the input is the quoted sold and the minimum output is the quoted bought reduced by slippage, rounded down. Buy: the output is the quoted bought and the maximum input is the quoted sold increased by slippage, rounded up.
4. It plans an approval for the input (exact or maximum) and calls the contract's swap.

slippage is a fraction rounded to basis points (0.005 is 0.5%) and defaults to 0. With 0 the swap succeeds only if the book still gives at least the quoted result, otherwise it fails with 709. A quote with no route throws the quote's error or No route available. The result is {sold, bought, approve}.

import {TradeDirection} from '@axis-markets/client'

const EURC = 'CCUUDM434BMZMYWYDITHFXHDMIVTGGD6T2I5UKNX5BSLXLW7HVR4MCGZ'

// sell 10 XLM for EURC, accept up to 0.5% less than quoted
const {sold, bought} = await account.swap({selling: XLM, buying: EURC, amount: 100_000_000n, slippage: 0.005})

// receive exactly 5 EURC, spend up to 1% more XLM than quoted
await account.swap({selling: XLM, buying: EURC, amount: 50_000_000n, direction: TradeDirection.Buy, slippage: 0.01})

Account events#

AccountFill is {order, sold, bought, taker, trade, ts, partial}. sold is the amount of the order's selling asset delivered, bought the amount of buying received, trade the trade ID, ts the trade time in UNIX milliseconds, and partial tells whether the order stays open.

Automatic allowance management#

The contract fills an order only up to min(balance, allowance) of its owner, and one allowance backs every order selling that token in every market (see Allowances and your funds). Before each sell, buy, swap and growing update, the account plans an approval with planApproval:

• required is what the call may spend: the amount of a sell, ceil(amount * price / 10^18) for a buy, the input (exact or maximum) of a swap, the growth of an update.
• The target is required + committed(asset), where committed includes this client's pending orders.
• No approval is sent when the current allowance already covers the target and does not expire within APPROVAL_RENEW_LEDGERS (17,280 ledgers, about 1 day).
• Otherwise the call carries an approval of exactly the target, valid for APPROVAL_TTL_LEDGERS (518,400 ledgers, about 30 days) from the current ledger.
• The account never revokes an allowance and does not shrink it after cancels. Every approval it sends sets the allowance to exactly this call plus the open orders selling the token, so a renewal near expiry can lower a larger allowance granted earlier. Revoke an allowance yourself with an update approval of 0 (see Contract client).

The approval travels inside the same transaction as the trade, so the user signs once. The account emits approve just before the call.

The current allowance comes from the pushed account state while the WebSocket is connected and the token is tracked. It is read over RPC when the connection is down, the token is not tracked, a backing reload is pending, or for 30 seconds after this client spent the token as a taker, because the push reporting the spend can lag. Without rpcUrl the last pushed value is used, and an untracked token throws. A failed RPC read counts as a zero allowance: the call then carries a redundant approval rather than fail.

Data freshness#

• connect() and every account subscribe to WebSocket channels. Each change arrives as a push.
• While the connection is down, Axis polls GET /contract and every account polls GET /account/:address every fallbackPollInterval (15 seconds by default). The stream reconnects with a delay that starts at 1 second and doubles up to 30 seconds, then resubscribes. The fresh snapshot reports orders that changed meanwhile as new and remove.
• An account loads over REST when no push snapshot arrives within 3 seconds. Trading methods wait up to 15 seconds for the account state, then throw.
• An order created by this client counts as committed for up to 2 minutes, or until the indexer reports it.
• getLedger() trusts the pushed ledger for 60 seconds, then reads it over RPC.

Errors thrown by the library#

Besides contract errors (Contract execution error: #NNN Name with a numeric code, see Errors), token errors (tokenError: true, see Contract client) and AxisApiError from REST calls, the classes throw these errors: