Stellar Aggregator API

Quote endpoint — forward (given input, maximize output) or reverse (given target output, minimize input).

When sender is set, the response gains a ready-to-sign transaction XDR envelope. With simulate=true (the default whenever sender is set) the envelope is server-side-prepared (resource-fee + footprint attached).

platform=all runs both Aggregator (Soroban) and SDEX (Classic) and returns the winning quote only; fire a second request with an explicit platform to fetch the loser if you need a side-by-side comparison.

GET

api

quote

Quote endpoint — forward (given input, maximize output) or reverse (given target output, minimize input).

curl --request GET \
  --url https://api.example.com/api/v1/quote

{
  "amountIn": "<string>",
  "amountInShort": 123,
  "amountOut": "<string>",
  "amountOutShort": 123,
  "decimalsIn": 1,
  "decimalsOut": 1,
  "from": "<string>",
  "mode": "forward",
  "platform": "aggregator",
  "rate": 123,
  "rateInverse": 123,
  "to": "<string>",
  "tokenInKind": "<string>",
  "tokenOutKind": "<string>",
  "amountInUsd": 123,
  "amountOutMin": "<string>",
  "amountOutMinShort": 123,
  "amountOutMinUsd": 123,
  "amountOutUsd": 123,
  "degraded": {
    "effectiveMaxHops": 1,
    "effectiveMaxSplits": 1,
    "fallbackAttempts": 1,
    "reason": "<string>",
    "requestedMaxHops": 1,
    "requestedMaxSplits": 1
  },
  "feeAmount": "<string>",
  "feeAmountShort": 123,
  "feeBps": 1,
  "feeOnInput": true,
  "paths": [
    {
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "splitPpm": 1,
      "swaps": [
        {
          "address": "<string>",
          "amountIn": "<string>",
          "amountInShort": 123,
          "amountOut": "<string>",
          "amountOutShort": 123,
          "dex": "<string>",
          "feeBps": 1,
          "from": "<string>",
          "kind": "<string>",
          "to": "<string>",
          "tokenInKind": "<string>",
          "tokenOutKind": "<string>"
        }
      ]
    }
  ],
  "priceImpact": 123,
  "slippage": 123,
  "transaction": {
    "baseFee": 1,
    "envelopeXdr": "<string>",
    "networkPassphrase": "<string>",
    "notes": "<string>",
    "routerContract": "<string>",
    "sourceAccount": "<string>",
    "latestLedger": 1,
    "minResourceFee": "<string>",
    "simulated": true
  }
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

Query Parameters

from

string

required

Token identifier. Accepts:

XLM / native: native lumen
CODE: first Classic asset matching code (e.g. "USDC")
CODE-SAC: Soroban Asset Contract form of that Classic asset
XLM-SAC: the SAC form of native XLM
CODE:GISSUER...: exact Classic in SEP-11 form
C... (56 chars): Soroban contract address directly

string

required

amount_in

string

Forward mode: input amount in RAW atomic units. Exactly ONE of amount_in or amount_out must be set. Accepts amount_in (snake) or amountIn (camel).

amount_out

string

Reverse mode: target output in RAW atomic units. The server computes the minimum amount_in that delivers at least this output. Accepts amount_out or amountOut.

max_hops

integer

Required range: x >= 0

max_splits

integer

Split across up to N paths to reduce slippage. Default 1 (no split). Only applies to forward quotes; reverse quotes use one path.

Required range: x >= 0

slippage

number<double>

Slippage tolerance as decimal (e.g. 0.01 = 1%). When set, response populates amountOutMin at amountOut * (1 - slippage).

includePaths

boolean

Opt in to the per-path breakdown (paths[]). Defaults to false — the response then carries totals + the prepared transaction only, even when the allocator splits across multiple pools. Set to true for debugging, analytics, or UIs that render the route.

sender

string

Sender G-strkey. When combined with router, the response gains transaction with a ready-to-sign envelope.

router

string

Router Soroban contract C-strkey. Optional — defaults to the configured network router (see Network::default_aggregator_router). Override only when targeting a non-standard router (tests, preview).

referral_id

integer<int64>

Referral identifier for fee attribution. 0 (default) means "no referral / no fee". Non-zero IDs MUST be registered on-chain via add_referral or the contract reverts at execution. Threaded into the BatchSwap so the on-chain router can charge admin + referral fees and accumulate them per (referral_id, token).

Required range: x >= 0

simulate

boolean

When true (default whenever sender is set), the server runs simulateTransaction itself and returns a prepared envelope — Soroban data + resource-fee already attached, total fee accurate. The caller skips its own simulate call before signing.

Set simulate=false to opt out (faster — saves ~150-300 ms per quote — at the cost of the caller running its own simulate before signing). When the simulator reports an error (typically Budget, ExceededLimit for over-large multi-path routes), the server returns HTTP 422 with the error message so the caller can retry with smaller maxSplits / maxHops.

platform

enum<string>

Execution-plane filter:

aggregator (default): Soroswap + Aquarius + Phoenix only. Produces a batch_execute envelope safe for composable contract-to-contract use (Lending → Aggregator).
sdex: Native AMM only. Today returns the route; envelope construction (Classic PathPaymentStrictReceive) lands in a follow-up.
all: runs both and returns whichever produces the larger amountOut (gas tiebreak: fewer hops). The losing platform's quote is dropped — fire a second request with the explicit platform=... if you need a side-by-side comparison. Which execution plane the quote should be valid for.

Stellar has two execution planes: Soroban (smart contracts) and Classic (SDEX orderbook + native AMM pools). A composable contract chain (Lending → Aggregator) MUST stay in Soroban — Classic ops can only be composed at envelope-construction time, before the user signs. A direct-user flow can use either plane independently.

Platform filters which PoolSource values beam search is allowed to expand. The default is Aggregator (Soroban-only) — that's the safer choice because every existing caller of the routing engine pre-platform expected Soroban results.

Available options:

aggregator,

sdex,

all

fresh

boolean

If true, compare the snapshot's last_applied_ledger against the network's live getLatestLedger before answering. If the snapshot is behind by more than MAX_FRESH_LEDGER_DRIFT ledgers, return HTTP 409 (Conflict) with a snapshot_stale body so the caller can retry. Costs one extra RPC round-trip; off by default.

Response

Route plus optional prepared transaction envelope

Top-level response carrying the route, prepared envelope (when sender is set), and enrichment fields (USD value, fee breakdown, auto-fallback metadata).

amountIn

string

required

Raw u128 string (precision-safe).

amountInShort

number<double>

required

f64 convenience for display (loses precision above 2^53).

amountOut

string

required

amountOutShort

number<double>

required

decimalsIn

integer<int32>

required

Required range: x >= 0

decimalsOut

integer<int32>

required

Required range: x >= 0

from

string

required

Canonical token identifier. "XLM" for native, "C..." for Soroban contracts, "CODE:GISSUER..." for Classic.

mode

string

required

"forward" or "reverse".

Example:

"forward"

platform

enum<string>

required

Which execution plane produced this quote. "aggregator" for Soroban-side routes (Soroswap / Aquarius / Phoenix / static bridges); "sdex" for Classic-plane routes (native AMM pools). The API returns this discriminator so consumers can branch on envelope type without inspecting the routes.

Available options:

aggregator,

sdex,

all

rate

number<double>

required

Output per 1 unit of input (f64).

rateInverse

number<double>

required

Input per 1 unit of output.

string

required

tokenInKind

string

required

Stellar extension: which token family was resolved. One of "native" | "classic" | "soroban". Matches the kind field in /api/v1/tokens.

tokenOutKind

string

required

amountInUsd

number<double> | null

USD value of amountIn (None when the input token has no Reflector oracle price on the active network).

amountOutMin

string | null

Minimum output after slippage (raw u128 string). Set only when slippage was provided in the request.

amountOutMinShort

number<double> | null

amountOutMinUsd

number<double> | null

USD value of amountOutMin (only set when slippage was set on the request and the output token has a price).

amountOutUsd

number<double> | null

USD value of amountOut.

degraded

null | object

Set when the server-side simulator rejected the requested configuration (typically Budget, ExceededLimit) and the quote was re-built with reduced maxSplits / maxHops to fit. Carries the actual config used so the caller can surface a "we routed through fewer paths" hint to the user.

Show child attributes

feeAmount

string | null

Fee amount the router will deduct (raw u128 string). Charged on the input token when feeOnInput=true, otherwise on the output token. The amountOut / amountOutMin already reflect this deduction.

feeAmountShort

number<double> | null

Display value of feeAmount (decimals applied; loses precision above 2^53).

feeBps

integer<int32> | null

Combined static + referral fee in basis points (1 bps = 0.01%) the router will charge for this swap. None when referralId == 0 or unknown — no referral means no fee.

Required range: x >= 0

feeOnInput

boolean | null

true if the fee is charged on the input token, false if charged on the output. Mirrors the contract's fee_on_input = !out_whitelisted || in_whitelisted rule. Absent when no fee applies.

paths

object[] | null

Per-path breakdown. Populated when the request includes includePaths=true. Even on multi-path splits the field stays absent by default — clients that need the route detail must opt in.

Show child attributes

priceImpact

number<double> | null

Price impact as decimal: 1 - executed_rate / spot_rate. 0.0 = no slippage, 0.02 = 2% below mid-market. Absent when spot rate can't be determined (no alternative depth info).

slippage

number<double> | null

Slippage tolerance as decimal (echoed from request).

transaction

null | object

Unsigned transaction envelope ready for the sender to sign + submit. Populated when the request included both sender=G... and router=C... query params. The envelope calls router.batch_execute(batch) where batch is derived from the paths in this response. Caller MUST:

Populate seqNum from the sender's account state.
Run simulateTransaction to attach Soroban resource fees.
Sign with sender's Ed25519 key.
Submit via sendTransaction.

Show child attributes

Quote endpoint — forward (given input, maximize output) or reverse (given target output, minimize input).

curl --request GET \
  --url https://api.example.com/api/v1/quote

{
  "amountIn": "<string>",
  "amountInShort": 123,
  "amountOut": "<string>",
  "amountOutShort": 123,
  "decimalsIn": 1,
  "decimalsOut": 1,
  "from": "<string>",
  "mode": "forward",
  "platform": "aggregator",
  "rate": 123,
  "rateInverse": 123,
  "to": "<string>",
  "tokenInKind": "<string>",
  "tokenOutKind": "<string>",
  "amountInUsd": 123,
  "amountOutMin": "<string>",
  "amountOutMinShort": 123,
  "amountOutMinUsd": 123,
  "amountOutUsd": 123,
  "degraded": {
    "effectiveMaxHops": 1,
    "effectiveMaxSplits": 1,
    "fallbackAttempts": 1,
    "reason": "<string>",
    "requestedMaxHops": 1,
    "requestedMaxSplits": 1
  },
  "feeAmount": "<string>",
  "feeAmountShort": 123,
  "feeBps": 1,
  "feeOnInput": true,
  "paths": [
    {
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "splitPpm": 1,
      "swaps": [
        {
          "address": "<string>",
          "amountIn": "<string>",
          "amountInShort": 123,
          "amountOut": "<string>",
          "amountOutShort": 123,
          "dex": "<string>",
          "feeBps": 1,
          "from": "<string>",
          "kind": "<string>",
          "to": "<string>",
          "tokenInKind": "<string>",
          "tokenOutKind": "<string>"
        }
      ]
    }
  ],
  "priceImpact": 123,
  "slippage": 123,
  "transaction": {
    "baseFee": 1,
    "envelopeXdr": "<string>",
    "networkPassphrase": "<string>",
    "notes": "<string>",
    "routerContract": "<string>",
    "sourceAccount": "<string>",
    "latestLedger": 1,
    "minResourceFee": "<string>",
    "simulated": true
  }
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}

{
  "error": "unknown token_in 'INVALID-123'"
}