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

# Stellar DEX Aggregator

> Quote Stellar swaps across Soroban and Classic sources, then request a prepared TransactionEnvelope when the user is ready to sign.

Use the Stellar Aggregator to quote swaps and, when `sender` is present, receive a prepared `TransactionEnvelope` for signing.

## Use This When

| Need                                                         | Use                                   |
| ------------------------------------------------------------ | ------------------------------------- |
| Quote a Soroban swap for contract composition                | `platform=aggregator`                 |
| Compare Soroban and Classic execution for a direct-user flow | `platform=all`                        |
| Return a prepared envelope with resource fee and footprint   | Add `sender` and keep `simulate=true` |
| Build a token picker                                         | `GET /api/v1/tokens`                  |

## Do Not Use This When

| Need                                                  | Use instead                                    |
| ----------------------------------------------------- | ---------------------------------------------- |
| You need MultiversX swap transaction data             | [MultiversX Aggregator](/aggregator/overview)  |
| You need Stellar lending account or pool behavior     | [Stellar Lending](/stellar-lending/overview)   |
| You already have an envelope and only need submission | Submit through your Stellar RPC or wallet flow |

## Base URL

```text theme={"system"}
https://stellar-swap.xoxno.com
```

No API key is required; per-IP rate limits apply.

## Flow

<Steps>
  <Step title="List or select tokens">
    Use `/api/v1/tokens` for routable token IDs. Prefer full C-strkeys or SEP-11 identifiers over aliases in deterministic flows.
  </Step>

  <Step title="Quote the route">
    Call `/api/v1/quote` with `from`, `to`, and exactly one of `amount_in` or `amount_out`.
  </Step>

  <Step title="Choose the execution plane">
    Keep `platform=aggregator` for composable Soroban flows. Use `platform=all` only when a user signs the final envelope directly.
  </Step>

  <Step title="Request and sign the envelope">
    Pass `sender` to receive `transaction.envelopeXdr`, a base64 XDR `TransactionEnvelope`.
  </Step>
</Steps>

## Execution Planes

| `platform`             | Sources                                         | Envelope behavior              | Use when                                                  |
| ---------------------- | ----------------------------------------------- | ------------------------------ | --------------------------------------------------------- |
| `aggregator` (default) | Soroswap, Aquarius, Phoenix, static SAC bridges | Soroban `batch_execute`        | A Soroban contract or app needs composable execution      |
| `sdex`                 | Stellar SDEX                                    | Classic path payment route     | A direct-user Classic flow controls envelope construction |
| `all`                  | Soroban and Classic sources                     | Returns only the winning quote | A direct-user UI wants a single displayed route           |

<Warning>
  Classic SDEX operations do not compose inside another Soroban contract. Use `platform=aggregator` for Lending -> Aggregator flows.
</Warning>

## Limits

| Action            | Limit or behavior                                             |
| ----------------- | ------------------------------------------------------------- |
| Any request       | 100 requests per second per IP                                |
| Quote freshness   | Quotes use the latest pool snapshot available to the service  |
| Snapshot refresh  | Soroban stream loop about every 5 s, sanity resync every 60 s |
| Liquidity sources | Soroswap, Aquarius, Phoenix, Stellar SDEX, static SAC bridges |
| Reverse quotes    | Single-path only                                              |
| Amount format     | Use integer strings in the token's smallest unit              |

## Endpoints

| Endpoint         | Method | Job                                                     |
| ---------------- | ------ | ------------------------------------------------------- |
| `/api/v1/quote`  | `GET`  | Quote a route and optionally return a prepared envelope |
| `/api/v1/tokens` | `GET`  | List routable tokens from the current snapshot          |
| `/health`        | `GET`  | Return service and snapshot status                      |
| `/ready`         | `GET`  | Return readiness, including stale-snapshot failures     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/stellar-aggregator/quickstart">
    Fetch a quote, inspect the envelope, and submit it through Stellar tooling.
  </Card>

  <Card title="Quote endpoint" icon="calculator" href="/stellar-aggregator/quote">
    Parameters, response fields, errors, and executable examples.
  </Card>

  <Card title="Tokens endpoint" icon="coins" href="/stellar-aggregator/tokens">
    Token identifiers, decimals, and source metadata.
  </Card>

  <Card title="Integration guide" icon="book-open" href="/stellar-aggregator/integration-guide">
    Handle prepared envelopes, fallback routes, retries, and errors.
  </Card>
</CardGroup>