Developers / Guides

Migrating from the Classic DEX

For apps that trade through Horizon and Classic offers today: how AXIS concepts, endpoints and data formats map to what you know, and what behaves differently.

AXIS and the Classic DEX are separate venues. Classic offers and liquidity pools stay on the Classic DEX, AXIS orders live in the AXIS contract, and neither venue matches against the other.

Concept map#

Endpoint mapping#

Full parameter lists are in REST API.

Data format differences#

Assets. Responses identify assets by contract address (C...): the Stellar Asset Contract of each Classic asset. Compute it with new Asset(code, issuer).contractId(networkPassphrase). /quote, /depth and /candles also accept XLM, native, CODE:ISSUER and CODE-ISSUER on input. /order, /trades and /order-history filter by contract address. Markets use the contract's canonical pair order, which compares the XDR bytes of the addresses, not their strings. Use canonicalPair from the JS client instead of sorting strings.

Amounts. Order, trade, quote and backing amounts are integer base units as strings: "1000000000" is 100 XLM, where Horizon writes "100.0000000". /depth, /candles and /ticker/24h are display data and use decimal strings.

Prices. Horizon uses an n/d rational (price_r) plus a decimal string. AXIS stores an 18-decimal integer: buying base units per selling base unit, times 10^18. A price of 0.25 is 250000000000000000. The valid range is 1 to 10^36. Order JSON adds rprice, an approximate number for display. See Prices and rounding.

Orientation. Orders are stored sell-equivalent. A buy order is stored as an order that sells the asset it pays with, at the inverted price. A ManageBuyOffer port must convert prices back for display.

IDs. Order IDs are 128-bit integers written as decimal strings. They are hashes, not counters, so never sort by ID. Trades and swaps have no on-chain ID: the AXIS API derives one from the ledger, transaction and event position.

Sorting and cursors. The paged list endpoints have no order parameter: /order returns oldest first, /trades and /order-history newest first. To page, pass the cursor field of the last row you received. Rows up to and including it are skipped. limit caps differ per endpoint: 200 for /order, 500 for /trades and /order-history, 1,000 for /markets.

No HAL. Responses are plain JSON arrays or objects, without _links or _embedded.records. Errors are {"error": "...", "status": code}, and unknown paths return a plain-text 404.

Converting values#

All Classic assets have 7 decimals, so prices between them carry over without a decimal adjustment:

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

// Horizon price_r {n, d} of a ManageSellOffer to an AXIS sell price
const toAxisPrice = ({n, d}) => BigInt(n) * PRICE_SCALE / BigInt(d)

// Horizon decimal amount string to base units of a 7-decimal asset
function toBaseUnits(value) {
    const [whole, fraction = ''] = value.split('.')
    return BigInt(whole + fraction.padEnd(7, '0').slice(0, 7))
}

toAxisPrice({n: 1, d: 4}) // 250000000000000000n, a price of 0.25
toBaseUnits('100.5') // 1005000000n

toAxisPrice rounds down, which for a sell order means a minimum price that is at most 10^-18 lower than the rational.

Behavior to handle#

• Rent per order. Creating an order pays about 0.041 XLM of ledger rent, not refunded on removal, and an order nobody updates archives after about 120 days. Requote with update instead of cancel and recreate. See Order lifecycle and rent.
• Allowances. Makers and takers grant the contract an absolute, expiring allowance per token they sell, and one allowance backs all orders selling that token. Build approval UX: see Wallet integration.
• Effective depth. An order is fillable only up to the maker's min(balance, allowance). The AXIS API counts only backed amounts. Show the backed field next to each order.
• 20 fills per transaction. One trade fills at most 20 orders from distinct makers, and one swap at most 20 across its hops. Large orders sweeping many levels may need several transactions. See Resource limits and costs.
• No Classic liquidity in AXIS routes. A path payment and an AXIS swap see different books. If you show both, quote both and compare.
• Takers choose the orders. A trade without listed orders matches nothing: a Limit trade then simply creates an order, even when it crosses the book. AxisAccount.sell and buy look up the crossing orders for you.
• Self-trades are allowed. The Classic DEX rejects an offer that would cross an offer of the same account. AXIS lets a trade fill the trader's own orders by design, so leave them out of the list when that is not intended.
• Skips instead of failures. A listed order whose maker cannot settle is skipped with a skip event, and the rest of the trade executes. See Failure modes.
• Markets and minimum size. Every limit order needs a market opened on-chain (721), a recent oracle price (722) and a minimum value in USD (720), checked on its whole amount even when it fills at once. Swaps and market orders need none of these.
• Fees from simulation. Network fees depend on the resources of each call. Read them from the simulated transaction.

Migration checklist#

1. Map every Classic asset you support to its contract address with Asset.contractId. Keep your trustline handling: it still applies.
2. Replace /order_book with /depth or the depth WebSocket channel. Both count only backed amounts.
3. Replace /paths/strict-send and /paths/strict-receive with /quote. Build swap calls from the quoted hops and set the bounds from the user's slippage.
4. Replace ManageSellOffer and ManageBuyOffer with trade (AxisAccount.sell and buy), offer updates with update and deletions with update amount 0.
5. Add allowance handling: absolute amounts, expiry, renewal before expiry, and the sum of open orders per token.
6. Show backing per order and react to orders that become unbacked.
7. Move history and charts to /trades, /order-history, /candles and /ticker/24h.
8. Replace server-sent event streams with WebSocket channel subscriptions.
9. Convert amounts to base units and prices to 18-decimal integers at the boundary of your app.
10. Read fees from simulation and map contract error codes to messages. See Errors.
11. Requote your orders with update and keep long-lived orders updated so they never archive.
12. Run the whole flow on Testnet first. See Networks and deployments.