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

# Quote endpoint

> Request a Stellar swap quote, route breakdown, and optional prepared TransactionEnvelope from the XOXNO Stellar Aggregator.

Request a Stellar swap quote and, when `sender` is present, receive a prepared `TransactionEnvelope` for signing.

## The endpoint

| Field        | Value                            |
| ------------ | -------------------------------- |
| Method       | `GET`                            |
| Path         | `/api/v1/quote`                  |
| Base URL     | `https://stellar-swap.xoxno.com` |
| Auth         | None                             |
| Availability | Public                           |
| Rate limit   | 100 requests per second per IP   |

## Required params

| Param                       | Type   | Description                                                                                         |
| --------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `from`                      | string | Input token: C-strkey, `XLM`, `XLM-SAC`, `CODE`, `CODE-SAC`, or `CODE:GISSUER...`.                  |
| `to`                        | string | Output token in the same forms as `from`.                                                           |
| `amount_in` or `amount_out` | string | Exactly one amount in raw atomic units. Camel-case aliases `amountIn` and `amountOut` are accepted. |

## Optional params

| Param                            | Type    | Default                     | Description                                                                                                     |
| -------------------------------- | ------- | --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `sender`                         | string  | none                        | Sender G-strkey. When set, the response includes `transaction.envelopeXdr` when envelope construction succeeds. |
| `simulate`                       | boolean | `true` when `sender` is set | Runs `simulateTransaction` and returns a prepared Soroban envelope with footprint and resource fee.             |
| `platform`                       | string  | `aggregator`                | `aggregator`, `sdex`, or `all`.                                                                                 |
| `slippage`                       | number  | none                        | Decimal slippage tolerance. Populates `amountOutMin` or `amountInMax`.                                          |
| `max_splits` / `maxSplits`       | number  | `1`                         | Maximum split paths. Forward quotes only; reverse quotes are single-path.                                       |
| `max_hops` / `maxHops`           | number  | `4`                         | Maximum hops per candidate path.                                                                                |
| `include_paths` / `includePaths` | boolean | `false`                     | Include `paths[]` route breakdown.                                                                              |
| `fresh`                          | boolean | `false`                     | Compare snapshot ledger against live ledger and return 409 when drift exceeds the service threshold.            |
| `router`                         | string  | network default             | Router contract C-strkey. Override for tests and previews.                                                      |
| `referral_id` / `referralId`     | number  | `0`                         | Referral ID. Non-zero IDs must be registered on-chain.                                                          |

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

## Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://stellar-swap.xoxno.com/api/v1/quote?\
    from=XLM&\
    to=USDC&\
    amount_in=1000000000&\
    platform=aggregator&\
    sender=GA..."
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    const params = new URLSearchParams({
      from: "XLM",
      to: "USDC",
      amount_in: "1000000000",
      platform: "aggregator",
      sender: "GA...",
    });

    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();
    console.log(quote.amountOut, quote.transaction?.envelopeXdr);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import httpx

    res = httpx.get(
        "https://stellar-swap.xoxno.com/api/v1/quote",
        params={
            "from": "XLM",
            "to": "USDC",
            "amount_in": "1000000000",
            "platform": "aggregator",
            "sender": "GA...",
        },
        timeout=15,
    )
    res.raise_for_status()

    quote = res.json()
    print(quote["amountOut"], quote.get("transaction", {}).get("envelopeXdr"))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    use reqwest::Client;
    use serde_json::Value;

    #[tokio::main]
    async fn main() -> Result<(), Box<dyn std::error::Error>> {
        let quote: Value = Client::new()
            .get("https://stellar-swap.xoxno.com/api/v1/quote")
            .query(&[
                ("from", "XLM"),
                ("to", "USDC"),
                ("amount_in", "1000000000"),
                ("platform", "aggregator"),
                ("sender", "GA..."),
            ])
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;

        println!("{} {}", quote["amountOut"], quote["transaction"]["envelopeXdr"]);
        Ok(())
    }
    ```
  </Tab>
</Tabs>

## Success response

```json theme={"system"}
{
  "amountIn": "1000000000",
  "amountOut": "425000000",
  "amountOutMin": "420750000",
  "amountInShort": 100,
  "amountOutShort": 42.5,
  "priceImpact": 0.002,
  "platform": "aggregator",
  "simulated": true,
  "transaction": {
    "envelopeXdr": "AAAAAgAAAAB...",
    "sourceAccount": "GA...",
    "networkPassphrase": "Public Global Stellar Network ; September 2015",
    "minResourceFee": "100345"
  }
}
```

## Response fields

| Field                        | Type   | Description                                                                      |
| ---------------------------- | ------ | -------------------------------------------------------------------------------- |
| `amountIn`                   | string | Input amount in raw atomic units.                                                |
| `amountOut`                  | string | Expected output amount in raw atomic units.                                      |
| `amountOutMin`               | string | Minimum output when `slippage` is set.                                           |
| `amountInMax`                | string | Maximum input for reverse quotes when `slippage` is set.                         |
| `amountInShort`              | number | Human-readable input amount.                                                     |
| `amountOutShort`             | number | Human-readable output amount.                                                    |
| `priceImpact`                | number | Estimated price impact as a decimal.                                             |
| `platform`                   | string | Execution plane used for the returned quote.                                     |
| `paths[]`                    | array  | Returned when `includePaths=true`.                                               |
| `transaction.envelopeXdr`    | string | Base64 XDR of the prepared `TransactionEnvelope`, returned when `sender` is set. |
| `transaction.minResourceFee` | string | Soroban resource fee when `simulate=true`.                                       |
| `degraded`                   | object | Present when the server reduced `maxSplits` or `maxHops` after a budget failure. |

## Execution planes

| `platform`   | Sources                                         | Use when                                                   |
| ------------ | ----------------------------------------------- | ---------------------------------------------------------- |
| `aggregator` | Soroswap, Aquarius, Phoenix, static SAC bridges | A Soroban flow needs composable execution.                 |
| `sdex`       | Stellar SDEX                                    | A direct-user Classic flow controls envelope construction. |
| `all`        | Soroban and Classic sources                     | A direct-user UI wants one selected quote across planes.   |

## Errors

| Status | Cause                                                                           | Fix                                                                                                  |
| ------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400`  | Missing token, invalid amount, or both amount fields set.                       | Fix query params and retry.                                                                          |
| `404`  | No route in the selected execution plane.                                       | Try another token pair or platform.                                                                  |
| `409`  | `fresh=true` and snapshot drift exceeds the service threshold.                  | Retry after the snapshot catches up.                                                                 |
| `422`  | Simulation failed, referral ID is invalid, or the route exceeds Soroban budget. | Lower `maxSplits` or `maxHops`, remove invalid referral, or retry without `sender` for pricing only. |
| `429`  | Per-IP rate limit exceeded.                                                     | Back off and queue requests client-side.                                                             |
| `503`  | Snapshot or service is unavailable.                                             | Retry with backoff.                                                                                  |

## Edge cases

| Case                           | Behavior                                                          | Client handling                                                                         |
| ------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `platform=all`                 | Returns one selected quote and drops the other plane.             | Make explicit `platform=aggregator` and `platform=sdex` calls for side-by-side display. |
| `simulate=false` with `sender` | Envelope is not prepared with Soroban footprint and resource fee. | Run Stellar simulation before signing.                                                  |
| Alias token IDs                | Aliases such as `USDC` resolve against the current snapshot.      | Use C-strkeys or SEP-11 IDs for deterministic flows.                                    |
| Reverse quote                  | Uses a single path.                                               | Do not depend on split allocation for reverse quotes.                                   |

## Verify

Before signing:

* `platform` matches the execution plane your flow can execute.
* `transaction.envelopeXdr` is present when your flow expects a `TransactionEnvelope`.
* `simulated` is `true` when you rely on server-prepared Soroban resources.
* Token amounts are raw atomic unit strings.
* The quote was generated after the latest user change to token, amount, slippage, sender, or platform.

## Related Guides

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