Oppia Swap Kit

A small TypeScript ESM library for comparing Stellar exact-input swap routes and building unsigned transactions. Four entry points: initialize, list assets, quote, and swap. Applications own signing and submission.

This is an initial implementation with explicit integration limits: public Aquarius and SDEX unsigned builds have been verified; xBull's public build endpoint currently returns HTTP 400; Soroswap needs credentials for live verification. Unverified Soroswap Soroban referral wrappers are excluded. See verification before integrating.

npm ci
npm run check
npm pack

Install the resulting tarball in your application. Requires Node.js 22+ or a modern browser with an application-controlled Soroswap transport. No package has been published.

import { OppiaSwapKit } from 'oppia-swap-kit';

const kit = new OppiaSwapKit({
  network: 'mainnet',
  rpcUrl,
  horizonUrl,
  providers: [
    { type: 'sdex' },
    {
      type: 'aquarius',
      feeCollector: {
        contractId: collectorAddress,
        destination: referralAddress,
        denominator: 10000,
      },
    },
    { type: 'xbull' },
    { type: 'soroswap', apiKey: process.env.SOROSWAP_API_KEY }, // server only
  ],
  referral: { address: referralAddress, feeBps: 30 },
});

const assets = await kit.getSupportedAssets();
const result = await kit.quote({
  sourceAddress,
  fromAsset: { type: 'native' },
  toAsset: { type: 'classic', code: 'USDC', issuer: usdcIssuer },
  amount: '10000000', // integer base units: 1 XLM
  slippageBps: 50,
  referral: { address: referralAddress, feeBps: 20 },
});
const swap = await kit.swap({ quote: result.best });
// swap.transactionXdr is unsigned. Review, sign and submit in your application.

new OppiaSwapKit(config) validates configuration without network calls. Network compatibility is verified on the first request. Provider order breaks equal-output ties. Configure only the providers you intend to use; default mainnet providers are xBull, Soroswap, Aquarius, and SDEX. Testnet omits xBull.

getSupportedAssets() returns { assets, issues, complete }. Each asset includes its canonical network identity, decimals, contract address, and available providers. Classic SAC addresses are derived and checked against the network. Contract tokens use { type: 'contract', contractId, decimals }; add classic: { code, issuer } only for a verified SAC. A catalog entry does not promise liquidity for a particular pair. Discovery is bounded and may report incomplete coverage.

quote(params) queries providers concurrently and returns { best, alternatives, issues, complete }. Amounts are integer strings, with bigint arithmetic throughout. Quotes expose net expected amountOut, net minAmountOut, route, fee asset/basis/settlement, and expiry. Network fees are null until build and do not affect output ranking. complete means all configured adapters returned valid quotes; it does not claim a global optimum across every Stellar pool. An aggregator's multi-hop or split route stays intact. We do not combine routes from different providers.

swap({ quote }) builds that route, checks accounts, balances and trustlines, validates transaction terms, and simulates Soroban calls. It returns unsigned XDR, network passphrase, expiry, input, net minimum, fees and a network fee budget in stroops. Actual network charges may be lower. It never chooses another provider on build failure. Request a fresh quote when the selected route fails or expires.

sourceAddress is optional. Omit it for an indicative quote: prices for a pair before a wallet is connected. Such a quote reports sourceAddress: null, and swap() rejects it with INVALID_QUOTE — re-quote with the connected account before building. Do not invent a placeholder account for price display.

Pass the original quote object to the same kit instance. Quotes are frozen and retained privately to prevent tampering; serialized/copy-constructed quotes are rejected. For JSON endpoints across multiple server workers, use the optional oppia-swap-kit/server bridge with authenticated quote tokens; see the Neko integration guide. Standard G… source accounts only; the source receives the output.

Referral defaults are optional. Per-quote settings replace the global setting, and referral: null disables it. feeBps: 0 also disables fees. There is one recipient and one rate per swap. Some providers share or defer fees; check the returned metadata rather than assuming the full fee immediately arrives at the recipient. If the referral recipient is also the swapping account, the fee is dropped rather than failing the quote.

A referral normally excludes providers that cannot carry it — notably every Soroswap Soroban route. Set required: false to keep that liquidity: those providers are re-quoted without the fee, and such a quote reports referral: null with no referral fee. Ranking stays on amountOut, so a fee-free route can win; read quote.referral and quote.fees to see what the selected route actually pays.

referral: { address: referralAddress, feeBps: 30, required: false },

| Provider | Referral basis | Settlement | | ---------------- | -------------------------------------------- | ---------------------------------------------------------- | | xBull | Output after platform fee | Native referral transfer; build endpoint currently failing | | Aquarius | Output, rounded up | Configured collector retains fees for later claiming | | Direct SDEX | Fixed amount rounded down from quoted output | Atomic payment in the swap transaction | | Soroswap SDEX | Input | Provider-defined split with Soroswap | | Soroswap Soroban | Not enabled | Excluded when a referral is required; wrapper not verified |

For direct SDEX, gross swap minimum = net user minimum + fixed referral payment. A failed payment rolls back the swap; the network transaction fee still applies. Aquarius/xBull fees vary with realized output, so quote fee amounts are estimates. Rates and minimums remain bound to the quote.

Defaults: slippage 50 bps, provider timeout 10 seconds, quote lifetime at most 30 seconds, base fee 100 stroops, maximum network fee 1 XLM. Override with slippageBps, timeoutMs, quoteTtlMs, baseFee, and maxNetworkFee where needed. HTTP provider URLs require HTTPS except localhost.

Errors are SwapKitError with a stable code. Provider failures are returned as issues; if none can quote, NO_ROUTE includes those issues. Setup failures such as TRUSTLINE_REQUIRED, TRUSTLINE_UNAUTHORIZED, INSUFFICIENT_BALANCE, and RESTORATION_REQUIRED require application action followed by a fresh quote. Builds reject stale quotes, incompatible contracts and mismatched transaction terms. Classic execution can still fail as ledger state changes after build.

• Neko-style server integration
• Provider configuration and primary sources
• Aquarius deployment and claiming
• Verification and integration gaps
• Basic usage, browser transport

npm run format                # Apply Prettier
npm run check                 # Formatting, typecheck, deterministic tests, build
RUN_LIVE=1 npm run test:live   # Read-only public quotes; Soroswap needs its key
RUN_LIVE=1 RUN_LIVE_BUILDS=1 npm run test:live # Unsigned mainnet builds only
RUN_TESTNET_SETTLEMENT=1 npm run test:live    # Ephemeral testnet accounts/transactions

Network tests are opt-in and excluded from CI. STELLAR_SOURCE selects an existing public account for unsigned build checks; STELLAR_RPC_URL overrides the mainnet RPC. Keep SOROSWAP_API_KEY in the server environment or gitignored .env. The library never logs or manages private keys.

Development layout: src/kit.ts coordinates the public API; src/config.ts resolves and snapshots settings; src/providers/ contains the adapters; src/stellar/ contains authorization and transfer validation. Provider tests live in tests/providers/, shared provider fixtures in tests/fixtures/, and authorization tests in tests/stellar/. CI runs the same formatting and verification checks as npm run check.