@axis-markets/client

JavaScript SDK for AXIS Stellar DEX.

• AxisContractClient — wraps the on-chain AXIS smart contract for order management and trading (sign & send transactions, read orders).
• ApiClient — a dependency-free HTTP client for the AXIS Aggregator and Indexer REST API (quotes, orderbook depth, candles, ticker, market/order/trade data).

Installation

npm i @axis-markets/client

Requires Node.js 20+ (or any modern browser).

AxisContractClient

Wraps the on-chain AXIS smart contract for trading and order management.

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

const client = new AxisContractClient({
    publicKey: 'G...', // trader public key
    contractId: 'C...', // AXIS contract id
    rpcUrl: 'https://soroban-rpc.stellar.org', // Stellar RPC server
    signTransaction: async (xdr, context) => ({signedTxXdr: await wallet.sign(xdr)}) // tx sign callback
})

// Read the last created order id
const lastId = await client.last()

// Fetch an order by id
const order = await client.order(lastId)

// Place a sell limit order (creates a limit order if not fully executed)
const [sold, bought, newOrderId] = await client.sell({
    kind: OrderKind.Limit,
    trader: 'G...',
    amount: 1_000_0000n,
    selling: 'C...selling',
    buying: 'C...buying',
    price: 5_000_000n,
    orders: []
})

// Cancel orders
await client.cancel([lastId], 'G...')

See src/index.d.ts for the full typed API (buy, sell, swap, fill_order, cancel, order, last).

Methods

| Method | Description | |---|---| | last() | Retrieve the last created order id. Returns Promise<bigint>. | | order(id) | Fetch an order by id from on-chain storage. Returns Promise<Order>. | | cancel(ids, trader) | Cancel existing orders (ids is a bigint[], trader is the owner address). Returns Promise<void>. | | fill_order(trader, takerOrderId, orders) | Fill existing orders using another matching order from the orderbook. Returns Promise<[sold, bought]>. | | buy(params) | Trade with the DEX and create a buy limit order if the quote is not fully executed (params: BuyTradeArguments). Returns Promise<[sold, bought, newOrderId]>. | | sell(params) | Trade with the DEX and create a sell limit order if the quote is not fully executed (params: SellTradeArguments). Returns Promise<[sold, bought, newOrderId]>. | | swap(params) | Swap tokens across several markets along a route (params: SwapArguments). Returns Promise<[sold, bought]>. |

Types

OrderKind

Trading order type — instructions to the contract on how to execute the trade.

| Value | Numeric | Description | |---|---|---| | Limit | 1 | Execute the trade, creating a limit order if not executed in full. | | Fill | 2 | Execute the trade without creating a limit order. | | FillOrKill | 3 | Execute the trade, cancel if it was not executed in full. |

TradeDirection

Trade direction instructions.

| Value | Numeric | Description | |---|---|---| | Sell | 1 | Sell the base asset. | | Buy | 2 | Buy the base asset. |

ClientInitializationParams

Parameters passed to the AxisContractClient constructor.

| Property | Type | Description | |---|---|---| | publicKey | string | Public key of the account that will interact with the contract. | | signTransaction | SignTransactionCallback | Callback for signing transactions generated by the client. | | rpcUrl | string | URL of the RPC server. | | contractId | string | DEX contract id. | | networkPassphrase? | string | Network passphrase (Pubnet passphrase by default). | | fee? | string | Transaction fee (0.1 XLM by default). |

SignTransactionCallback

(tx: string, context: {network, networkPassphrase, accountToSign}) => Promise<{signedTxXdr, signerAddress?}>

Callback for signing transactions generated by the client. Receives the transaction XDR to sign plus the signing context, and resolves to the signed transaction response.

TradeArguments

Base arguments shared by buy and sell.

| Property | Type | Description | |---|---|---| | kind | OrderKind | Trading order behavior. | | trader | string | Trader address. | | amount | bigint | Tokens amount. | | selling | string | Selling token address. | | buying | string | Buying token address. | | price | bigint | Price a trader is willing to accept. | | orders | bigint[] | List of order IDs to match before creating the order on-chain. |

SellTradeArguments

Extends TradeArguments (passed to sell).

| Property | Type | Description | |---|---|---| | amount | bigint | Amount of selling tokens to sell. | | price | bigint | Price a trader is willing to accept — minimum buying tokens per 1 selling. |

BuyTradeArguments

Extends TradeArguments (passed to buy).

| Property | Type | Description | |---|---|---| | amount | bigint | Amount of buying tokens to acquire. | | price | bigint | Price a trader is willing to accept — maximum selling tokens per 1 buying. |

TradeStep

A trade step in a multi-market swap path.

| Property | Type | Description | |---|---|---| | asset | string | Asset to buy at this step. | | orders | bigint[] | Maker order IDs to match. |

SwapArguments

Arguments passed to swap.

| Property | Type | Description | |---|---|---| | direction | TradeDirection | Trade direction: Sell or Buy. | | trader | string | Trader address. | | selling | string | Token address sent by the trader. | | sellingAmount | bigint | Maximum amount of selling tokens to send. | | buyingAmount | bigint | Minimum amount of buying tokens to receive. | | path | TradeStep[] | Ordered list of the trade route steps. |

Order

Order properties, stored on-chain (returned by order() call).

| Property | Type | Description | |---|---|---| | id | bigint | Order ID. | | kind | OrderKind | Trading behavior. | | owner | string | Owner of the order. | | selling | string | Selling token address. | | buying | string | Buying token address. | | amount | bigint | Amount of tokens to sell. | | price | bigint | Price of the order. | | quote | bigint | Total amount of tokens to buy. | | expires | bigint | Expiration time of the order. |

TradeContractEvent

Orderbook trade event emitted by the contract.

| Property | Type | Description | |---|---|---| | id | bigint | Unique trade id. | | order | bigint | Order id. | | taker | string | Trader account address. | | maker | string | Seller account address. | | selling | string | Sold asset address. | | buying | string | Bought asset address. | | sold | bigint | Sold tokens amount. | | bought | bigint | Bought tokens amount. |

SwapContractEvent

Orderbook swap event emitted by the contract.

| Property | Type | Description | |---|---|---| | id | bigint | Unique swap id (last trade id assigned while settling the swap legs). | | trader | string | Trader account address. | | selling | string | Sold asset address. | | buying | string | Bought asset address. | | sold | bigint | Amount of selling tokens sold. | | bought | bigint | Amount of buying tokens received. |

ApiClient

HTTP client for the AXIS Aggregator REST API. Uses the standard fetch API - no extra dependencies.

import {ApiClient, AxisApiError} from '@axis-markets/client'

const api = new ApiClient('https://aggregator.axis.markets')

// Quote: sell a fixed amount of the source asset (strict send)
const sellQuote = await api.quoteSell({
    sellingAsset: 'XLM',
    buyingAsset: 'USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
    amount: '10000000' // stroops (1 unit = 10,000,000 stroops)
})

// Quote: buy a fixed amount of the destination asset (strict receive)
const buyQuote = await api.quoteBuy({
    sellingAsset: 'XLM',
    buyingAsset: 'USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
    amount: '5000000'
})

// Order book depth around the mid price
const depth = await api.getDepth({market: 'XLM/USDC', depth: 20})

// OHLCVT candles
const candles = await api.getCandles({market: 'XLM/USDC', resolution: '1h', order: 'asc'})

// 24h ticker for every market
const {ticker} = await api.getTicker24h()

ApiClient Methods

| Method | Description | |---|---| | quoteSell({sellingAsset, buyingAsset, amount, direct?}) | Best trade routes for selling a fixed amount of the source asset (strict send). | | quoteBuy({sellingAsset, buyingAsset, amount, direct?}) | Best trade routes for buying a fixed amount of the destination asset (strict receive). | | getDepth({market, depth?}) | Order book depth aggregated into price buckets around the mid price (depth is the ± band %, 0–100, default 20). | | getCandles({market, from?, to?, resolution?, order?}) | OHLCVT candlestick data. resolution accepts seconds or an alias (5m, 15m, 30m, 1h, 2h, 4h, 12h, 1d, 3d, 1w, 2w; default auto). | | getTicker24h() | 24-hour ticker statistics for every available market. | | getMarkets({cursor?, limit?}) | List all active markets with pagination. | | getOrders({owner?, asset?, cursor?, limit?}) | Active orders, filterable by owner or asset (asset may be a string or string array). | | getOrder(id) | A single active order by ID (null if not found). | | getOrderHistory({owner?, pair?, cursor?, limit?}) | Archived/historical orders (pair = [base, quote] contract ids). | | getTrades({trader?, pair?, cursor?, limit?}) | Recent trades (pair = [base, quote] contract ids). |

Assets accept Soroban contract id or classic asset string formats like XLM, CODE:Issuer, CODE-Issuer. Markets use BASE/QUOTE convention. Amounts are expressed in stroops on input and returned as strings.

Error handling

Non-success responses throw an AxisApiError carrying the HTTP status code:

try {
    await api.getOrder('123')
} catch (e) {
    if (e instanceof AxisApiError && e.status === 404) {
        // not found
    }
    throw e
}

Development

Bundling script:

npm run prepare

Bundles the ESM source (src/) into a UMD distributable (lib/) via webpack. Type definitions are published from src/index.d.ts.

License

MIT