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

# Quickstart

> List Stellar tokens, request a quote, inspect a prepared TransactionEnvelope, and verify the response before signing.

List Stellar tokens, request a swap quote, and verify the prepared `TransactionEnvelope` before signing.

## Prerequisites

| Requirement             | Value                                    |
| ----------------------- | ---------------------------------------- |
| Base URL                | `https://stellar-swap.xoxno.com`         |
| Auth                    | None                                     |
| Rate limit              | 100 requests per second per IP           |
| Amount format           | Raw atomic unit strings                  |
| Default execution plane | `platform=aggregator` for Soroban routes |

## 1. List Tokens

Read token identifiers and decimals from `/api/v1/tokens`.

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://stellar-swap.xoxno.com/api/v1/tokens"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    const tokenRes = await fetch("https://stellar-swap.xoxno.com/api/v1/tokens");
    if (!tokenRes.ok) throw new Error(`tokens failed: ${tokenRes.status}`);

    const tokens = await tokenRes.json();
    const routable = tokens.filter((token: { degree: number }) => token.degree > 0);
    console.log(routable.length);
    ```
  </Tab>

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

    res = requests.get("https://stellar-swap.xoxno.com/api/v1/tokens", timeout=10)
    res.raise_for_status()

    tokens = res.json()
    routable = [token for token in tokens if token.get("degree", 0) > 0]
    print(len(routable))
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    // Run inside an async function with reqwest and serde_json.
    let tokens: Vec<serde_json::Value> = reqwest::Client::new()
        .get("https://stellar-swap.xoxno.com/api/v1/tokens")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let routable = tokens
        .iter()
        .filter(|token| token["degree"].as_i64().unwrap_or(0) > 0)
        .count();

    println!("{routable}");
    ```
  </Tab>
</Tabs>

Use `decimals` to convert human-readable amounts. For example, 100 XLM with 7 decimals is `1000000000`.

## 2. Request A Quote

Quote 100 XLM to USDC on the Soroban execution plane.

<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"
    ```
  </Tab>

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

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

    const quote = await quoteRes.json();
    console.log(quote.amountOut, quote.platform);
    ```
  </Tab>

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

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

    quote = res.json()
    print(quote["amountOut"], quote["platform"])
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={"system"}
    // Run inside an async function with reqwest and serde_json.
    let quote: serde_json::Value = reqwest::Client::new()
        .get("https://stellar-swap.xoxno.com/api/v1/quote")
        .query(&[
            ("from", "XLM"),
            ("to", "USDC"),
            ("amount_in", "1000000000"),
            ("platform", "aggregator"),
        ])
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

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

Inspect these fields:

| Field            | Use                                            |
| ---------------- | ---------------------------------------------- |
| `amountOut`      | Raw output amount.                             |
| `amountOutShort` | Display output amount.                         |
| `platform`       | Execution plane used for the route.            |
| `priceImpact`    | Decimal price impact estimate, when available. |

## 3. Request A Prepared Envelope

Pass `sender` when the user is ready to sign.

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

The response can include:

| Field                        | Meaning                                                             |
| ---------------------------- | ------------------------------------------------------------------- |
| `transaction.envelopeXdr`    | Base64 XDR `TransactionEnvelope`.                                   |
| `simulated`                  | `true` when the server prepared Soroban footprint and resource fee. |
| `transaction.minResourceFee` | Soroban resource fee attached during simulation.                    |

<Warning>
  When `simulate=true`, do not run `simulateTransaction` again on the returned envelope. Refresh sequence number, sign, and submit.
</Warning>

## Verify

You have a valid quickstart result when:

* `/api/v1/tokens` returns the selected token with `degree > 0`.
* `/api/v1/quote` returns non-zero `amountOut`.
* `platform` matches the execution plane your flow can execute.
* `transaction.envelopeXdr` is present when `sender` is set.
* `simulated` is `true` when your flow depends on server-prepared Soroban resources.

## Common Failure

| Symptom                              | Cause                                                                       | Fix                                                                      |
| ------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `409 snapshot_stale`                 | `fresh=true` and the snapshot is more than the allowed ledger drift behind. | Retry after the snapshot catches up.                                     |
| No `transaction` field               | `sender` was omitted or envelope construction failed.                       | Requote with `sender`; inspect 422 errors for budget or referral issues. |
| Contract flow receives Classic route | `platform=all` selected SDEX.                                               | Use `platform=aggregator` for Soroban composition.                       |

## Next Steps

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