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. |
Classic SDEX operations do not compose inside another Soroban contract. Keep platform=aggregator for contract-to-contract flows.
Request
cURL
TypeScript
Python
Rust
curl "https://stellar-swap.xoxno.com/api/v1/quote?\
from=XLM&\
to=USDC&\
amount_in=1000000000&\
platform=aggregator&\
sender=GA..."
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);
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"))
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(())
}
Success response
{
"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.