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

​
Prerequisites

RequirementWhy
Stellar wallet or signerThe Aggregator returns an envelope; it does not sign for the user.
Token metadataAmounts are raw atomic unit strings.
Execution plane decisionSoroban and Classic routes are not interchangeable.
Submission pathUse your Stellar RPC or wallet flow after signing.

​
Flow

1

Load token metadata

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

Choose the execution plane

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

Quote for display

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

Requote with sender at confirmation

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

Refresh sequence, sign, submit

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

​
Implementation Checklist

CheckRequired handling
Token alias selectedStore the returned canonical id; aliases can resolve differently across snapshots.
Contract-to-contract flowUse platform=aggregator.
Direct-user comparisonUse platform=all, then inspect the returned platform.
simulate=trueDo not rerun simulateTransaction on the prepared envelope.
simulate=falseYour client must simulate and prepare resources before signing.
HTTP 409Snapshot freshness gate failed; retry after the snapshot catches up.
HTTP 422Budget, 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.