Integration guide - XOXNO Docs

Integrate the Stellar Aggregator by reading token metadata, choosing an execution plane, requesting a quote, and signing the returned TransactionEnvelope.

Prerequisites

Requirement	Why
Stellar wallet or signer	The Aggregator returns an envelope; it does not sign for the user.
Token metadata	Amounts are raw atomic unit strings.
Execution plane decision	Soroban and Classic routes are not interchangeable.
Submission path	Use your Stellar RPC or wallet flow after signing.

Flow

Load token metadata

Call /api/v1/tokens and store the canonical id, decimals, kind, and sacPeer.

Choose the execution plane

Use platform=aggregator for Soroban composition. Use platform=all only when a direct-user UI can accept either plane.

Quote for display

Call /api/v1/quote without sender for price display.

Requote with sender at confirmation

Pass sender to receive transaction.envelopeXdr. Keep simulate=true unless your client prepares Soroban resources itself.

Refresh sequence, sign, submit

Set the sequence number from the live account, sign with the sender key, and submit through Stellar tooling.

Implementation Checklist

Check	Required handling
Token alias selected	Store the returned canonical `id`; aliases can resolve differently across snapshots.
Contract-to-contract flow	Use `platform=aggregator`.
Direct-user comparison	Use `platform=all`, then inspect the returned `platform`.
`simulate=true`	Do not rerun `simulateTransaction` on the prepared envelope.
`simulate=false`	Your client must simulate and prepare resources before signing.
HTTP `409`	Snapshot freshness gate failed; retry after the snapshot catches up.
HTTP `422`	Budget, referral, or simulation failure; lower `maxSplits` or `maxHops`, or fix referral config.

Classic SDEX operations do not compose inside another Soroban contract. Reject Classic results for Lending -> Aggregator flows.

Minimal TypeScript Shape

async function getPreparedEnvelope(sender: string) {
  const params = new URLSearchParams({
    from: "XLM",
    to: "USDC",
    amount_in: "1000000000",
    platform: "aggregator",
    sender,
  });

  const res = await fetch(`https://stellar-swap.xoxno.com/api/v1/quote?${params}`);
  if (!res.ok) throw new Error(`quote failed: ${res.status}`);

  const quote = await res.json();
  if (!quote.transaction?.envelopeXdr) {
    throw new Error("quote did not include envelopeXdr");
  }

  return quote.transaction.envelopeXdr;
}

Verify Before Signing

The selected token has degree > 0 in /api/v1/tokens.
Amounts are raw atomic unit strings.
platform matches the flow you can execute.
transaction.envelopeXdr is present.
simulated is true when you rely on the server-prepared Soroban footprint.
The quote was requested after the latest user change to token, amount, sender, slippage, or platform.

​Prerequisites

​Flow

​Implementation Checklist

​Minimal TypeScript Shape

​Verify Before Signing

​Related Pages

Prerequisites

Flow

Implementation Checklist

Minimal TypeScript Shape

Verify Before Signing

Related Pages