> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration guide

> Wire the Stellar Aggregator into a wallet flow from token discovery to prepared TransactionEnvelope signing.

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

<Steps>
  <Step title="Load token metadata">
    Call [`/api/v1/tokens`](/stellar-aggregator/tokens) and store the canonical `id`, `decimals`, `kind`, and `sacPeer`.
  </Step>

  <Step title="Choose the execution plane">
    Use `platform=aggregator` for Soroban composition. Use `platform=all` only when a direct-user UI can accept either plane.
  </Step>

  <Step title="Quote for display">
    Call [`/api/v1/quote`](/stellar-aggregator/quote) without `sender` for price display.
  </Step>

  <Step title="Requote with sender at confirmation">
    Pass `sender` to receive `transaction.envelopeXdr`. Keep `simulate=true` unless your client prepares Soroban resources itself.
  </Step>

  <Step title="Refresh sequence, sign, submit">
    Set the sequence number from the live account, sign with the sender key, and submit through Stellar tooling.
  </Step>
</Steps>

## 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. |

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

## Minimal TypeScript Shape

```ts theme={"system"}
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.

## Related Pages

* [Quickstart](/stellar-aggregator/quickstart)
* [Quote endpoint](/stellar-aggregator/quote)
* [Tokens endpoint](/stellar-aggregator/tokens)
* [Stellar execution planes](/stellar-aggregator/execution-planes)
* [Quote freshness](/resources/quote-freshness)
* [Token amounts](/resources/token-amounts)