Skip to main content
Request a Stellar swap quote and, when sender is present, receive a prepared TransactionEnvelope for signing.

The endpoint

FieldValue
MethodGET
Path/api/v1/quote
Base URLhttps://stellar-swap.xoxno.com
AuthNone
AvailabilityPublic
Rate limit100 requests per second per IP

Required params

ParamTypeDescription
fromstringInput token: C-strkey, XLM, XLM-SAC, CODE, CODE-SAC, or CODE:GISSUER....
tostringOutput token in the same forms as from.
amount_in or amount_outstringExactly one amount in raw atomic units. Camel-case aliases amountIn and amountOut are accepted.

Optional params

ParamTypeDefaultDescription
senderstringnoneSender G-strkey. When set, the response includes transaction.envelopeXdr when envelope construction succeeds.
simulatebooleantrue when sender is setRuns simulateTransaction and returns a prepared Soroban envelope with footprint and resource fee.
platformstringaggregatoraggregator, sdex, or all.
slippagenumbernoneDecimal slippage tolerance. Populates amountOutMin or amountInMax.
max_splits / maxSplitsnumber1Maximum split paths. Forward quotes only; reverse quotes are single-path.
max_hops / maxHopsnumber4Maximum hops per candidate path.
include_paths / includePathsbooleanfalseInclude paths[] route breakdown.
freshbooleanfalseCompare snapshot ledger against live ledger and return 409 when drift exceeds the service threshold.
routerstringnetwork defaultRouter contract C-strkey. Override for tests and previews.
referral_id / referralIdnumber0Referral 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 "https://stellar-swap.xoxno.com/api/v1/quote?\
from=XLM&\
to=USDC&\
amount_in=1000000000&\
platform=aggregator&\
sender=GA..."

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

FieldTypeDescription
amountInstringInput amount in raw atomic units.
amountOutstringExpected output amount in raw atomic units.
amountOutMinstringMinimum output when slippage is set.
amountInMaxstringMaximum input for reverse quotes when slippage is set.
amountInShortnumberHuman-readable input amount.
amountOutShortnumberHuman-readable output amount.
priceImpactnumberEstimated price impact as a decimal.
platformstringExecution plane used for the returned quote.
paths[]arrayReturned when includePaths=true.
transaction.envelopeXdrstringBase64 XDR of the prepared TransactionEnvelope, returned when sender is set.
transaction.minResourceFeestringSoroban resource fee when simulate=true.
degradedobjectPresent when the server reduced maxSplits or maxHops after a budget failure.

Execution planes

platformSourcesUse when
aggregatorSoroswap, Aquarius, Phoenix, static SAC bridgesA Soroban flow needs composable execution.
sdexStellar SDEXA direct-user Classic flow controls envelope construction.
allSoroban and Classic sourcesA direct-user UI wants one selected quote across planes.

Errors

StatusCauseFix
400Missing token, invalid amount, or both amount fields set.Fix query params and retry.
404No route in the selected execution plane.Try another token pair or platform.
409fresh=true and snapshot drift exceeds the service threshold.Retry after the snapshot catches up.
422Simulation 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.
429Per-IP rate limit exceeded.Back off and queue requests client-side.
503Snapshot or service is unavailable.Retry with backoff.

Edge cases

CaseBehaviorClient handling
platform=allReturns one selected quote and drops the other plane.Make explicit platform=aggregator and platform=sdex calls for side-by-side display.
simulate=false with senderEnvelope is not prepared with Soroban footprint and resource fee.Run Stellar simulation before signing.
Alias token IDsAliases such as USDC resolve against the current snapshot.Use C-strkeys or SEP-11 IDs for deterministic flows.
Reverse quoteUses 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.