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

GET

api

quote

curl --request GET \
  --url https://stellar-swap.xoxno.com/api/v1/quote

{
  "amountIn": "<string>",
  "amountInShort": 123,
  "amountOut": "<string>",
  "amountOutShort": 123,
  "decimalsIn": 1,
  "decimalsOut": 1,
  "from": "<string>",
  "hops": [
    {
      "address": "<string>",
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "dex": "<string>",
      "feeBps": 1,
      "from": "<string>",
      "kind": "<string>",
      "to": "<string>",
      "tokenInKind": "<string>",
      "tokenOutKind": "<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,
  "lp": {
    "amounts": [
      {
        "amount": "<string>",
        "amountShort": 123,
        "token": "<string>",
        "tokenKind": "<string>"
      }
    ],
    "dex": "<string>",
    "feeBps": 1,
    "kind": "<string>",
    "pool": "<string>",
    "shareToken": "<string>",
    "preSwap": {
      "address": "<string>",
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "dex": "<string>",
      "feeBps": 1,
      "from": "<string>",
      "kind": "<string>",
      "to": "<string>",
      "tokenInKind": "<string>",
      "tokenOutKind": "<string>"
    },
    "refunded": [
      {
        "amount": "<string>",
        "amountShort": 123,
        "token": "<string>",
        "tokenKind": "<string>"
      }
    ]
  },
  "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,
  "routeXdr": "<string>",
  "slippage": 123,
  "snapshot": {
    "ageSeconds": 1,
    "ledger": 1,
    "checkedLiveLedger": 1
  },
  "transaction": {
    "baseFee": 1,
    "envelopeXdr": "<string>",
    "networkPassphrase": "<string>",
    "notes": "<string>",
    "routerContract": "<string>",
    "sourceAccount": "<string>",
    "latestLedger": 1,
    "minResourceFee": "<string>",
    "simulated": true
  },
  "transactions": [
    {
      "baseFee": 1,
      "envelopeXdr": "<string>",
      "networkPassphrase": "<string>",
      "notes": "<string>",
      "routerContract": "<string>",
      "sourceAccount": "<string>",
      "latestLedger": 1,
      "minResourceFee": "<string>",
      "simulated": true
    }
  ]
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

Query Parameters

from

string

required

Input Soroban token contract. Resolve IDs and decimals through /api/v1/tokens.

Required string length: 56

string

required

Output Soroban token contract; a share-token ID selects a liquidity operation.

Required string length: 56

amount_in

string

Exact gross input in atomic units, including any input-side fee. Exactly one of amount_in / amount_out is required. Alias: amountIn. Range: 1..=i128::MAX.

amount_out

string

Required net output after swap fees, in atomic units. Computes the input needed; executable strategies enforce this target as a minimum. Alias: amountOut.

max_hops

integer

default:4

Maximum swaps per candidate path. Capped at 3 when the requested amount's locally derived USD value is below $10; lower limits stay lower. Alias: maxHops.

Required range: 1 <= x <= 6

max_splits

integer

default:8

Maximum split paths. Set 1 for a single path. Legacy 0 is treated as 1. Capped at 3 below $10 using the requested amount's local USD value; lower limits stay lower. Alias: maxSplits.

Required range: 0 <= x <= 8

slippage

number<double>

Output tolerance: 0.01 = 1%, finite and in [0,1). Required for executable payloads; omit for indicative amounts only. Rounded down to parts per million. Reverse quotes never permit output below the requested net target.

Required range: x >= 0

include_paths

boolean

default:false

Include per-path swaps and split weights. Totals always include every path. Alias: includePaths.

sender

string

Account G-strkey. Requires slippage; adds an unsigned standalone envelope. Without sender, slippage still enables routeXdr for contract composition.

Required string length: 56

referral_id

integer<int64>

default:0

Active on-chain referral ID, limited to the program's u32 range. Zero means no referral and no protocol fee. Aliases: referralId, referral.

Required range: 0 <= x <= 4294967295

simulate

boolean

default:true

With sender, simulate and prepare resource data. False returns an unprepared envelope. Budget failures may retry smaller routes, preserving the original output minimum. Ignored without sender. Composition requires its own simulation.

platform

enum<string>

default:aggregator

Soroban execution only. Kept for compatibility. Execution platform for quotes. The protocol is Soroban-only, so the only platform is the composable aggregator plane.

Available options:

aggregator

fresh

boolean

default:false

Check live RPC ledger against the exact snapshot used for this quote. Reject drift above two ledgers with 409. Adds one RPC request.

Response

Best net-output route found within search/execution limits, with optional execution payload

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

amountIn

string

required

Gross input debited from the user, including any input-side fee; atomic integer string.

amountInShort

number<double>

required

Gross input in whole-token units; approximate display value, not transaction arithmetic.

amountOut

string

required

Expected net output after aggregator/referral fees; atomic integer string. Successful standalone simulation replaces the model estimate with its delivered output.

amountOutShort

number<double>

required

Net output in whole-token units; approximate display value.

decimalsIn

integer<int32>

required

Input token decimal precision.

Required range: x >= 0

decimalsOut

integer<int32>

required

Output token decimal precision.

Required range: x >= 0

from

string

required

Canonical Soroban token contract identifier.

hops

object[]

required

Flat hop list (concatenation of all paths when split).

Kept in the public response for compatibility. paths is the richer per-path breakdown when the caller asks for includePaths=true.

Show child attributes

mode

string

required

forward, reverse, addLiquidity, removeLiquidity, or convertLiquidity.

Example:

"forward"

platform

enum<string>

required

Which execution plane produced this quote. Always "aggregator".

Available options:

aggregator

rate

number<double>

required

Expected net output per whole unit of gross input; approximate.

rateInverse

number<double>

required

Gross input per whole unit of expected net output; approximate.

string

required

Output token contract C-strkey.

tokenInKind

string

required

Token role: soroban for ordinary tokens or lp for share tokens.

tokenOutKind

string

required

Output role: soroban or lp.

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

Enforced net-output floor in atomic units when slippage is supplied. Reverse quotes preserve the requested target; fallback and simulation never lower this floor.

amountOutMinShort

number<double> | null

Net-output floor in whole-token units; approximate display value.

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 admin and referral fee in basis points (1 bps = 0.01%). Absent when no fee applies or an LP conversion spans fees in different tokens.

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 or an LP conversion spans fees in different tokens.

null | object

Liquidity breakdown for addLiquidity / removeLiquidity quotes: the pool, the per-constituent deposit/withdraw amounts, and the zap pre-swap when the mint balances inside its own pool. Purely informational (route visualization) — execution still comes from the encoded payload. Absent for ordinary swaps.

Show child attributes

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

Modelled execution impact as a decimal, excluding aggregator/referral fees. Uses sufficiently deep oracle-anchored prices when available, otherwise route spot rates. Absent when no reference exists; not recalculated from standalone simulation.

routeXdr

string | null

Base64 ScVal XDR containing the complete opaque strategy payload; requires slippage. Pass decoded bytes to execute_strategy(sender, total_in, swap_xdr). For LP conversion this optional atomic alternative can differ from transactions; its presence does not prove execution-budget feasibility. Simulate the complete composed call.

slippage

number<double> | null

Slippage tolerance as decimal (echoed from request).

snapshot

null | object

Snapshot used to search this quote; independent of the simulation ledger.

Show child attributes

transaction

null | object

Unsigned standalone transaction, present when sender and slippage are supplied. With transaction.simulated=true, the live source sequence is already set. Otherwise populate the sequence, simulate and assemble resource data first. Then sign, submit, and poll for confirmation. A composed controller transaction needs its own simulation.

Show child attributes

transactions

object[] | null

Ordered standalone LP-conversion steps, present with sender and slippage. Confirm each step before preparing the next; later steps require fresh simulation. Mutually exclusive with transaction; optional routeXdr is a separate atomic alternative.

Show child attributes

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

curl --request GET \
  --url https://stellar-swap.xoxno.com/api/v1/quote

{
  "amountIn": "<string>",
  "amountInShort": 123,
  "amountOut": "<string>",
  "amountOutShort": 123,
  "decimalsIn": 1,
  "decimalsOut": 1,
  "from": "<string>",
  "hops": [
    {
      "address": "<string>",
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "dex": "<string>",
      "feeBps": 1,
      "from": "<string>",
      "kind": "<string>",
      "to": "<string>",
      "tokenInKind": "<string>",
      "tokenOutKind": "<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,
  "lp": {
    "amounts": [
      {
        "amount": "<string>",
        "amountShort": 123,
        "token": "<string>",
        "tokenKind": "<string>"
      }
    ],
    "dex": "<string>",
    "feeBps": 1,
    "kind": "<string>",
    "pool": "<string>",
    "shareToken": "<string>",
    "preSwap": {
      "address": "<string>",
      "amountIn": "<string>",
      "amountInShort": 123,
      "amountOut": "<string>",
      "amountOutShort": 123,
      "dex": "<string>",
      "feeBps": 1,
      "from": "<string>",
      "kind": "<string>",
      "to": "<string>",
      "tokenInKind": "<string>",
      "tokenOutKind": "<string>"
    },
    "refunded": [
      {
        "amount": "<string>",
        "amountShort": 123,
        "token": "<string>",
        "tokenKind": "<string>"
      }
    ]
  },
  "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,
  "routeXdr": "<string>",
  "slippage": 123,
  "snapshot": {
    "ageSeconds": 1,
    "ledger": 1,
    "checkedLiveLedger": 1
  },
  "transaction": {
    "baseFee": 1,
    "envelopeXdr": "<string>",
    "networkPassphrase": "<string>",
    "notes": "<string>",
    "routerContract": "<string>",
    "sourceAccount": "<string>",
    "latestLedger": 1,
    "minResourceFee": "<string>",
    "simulated": true
  },
  "transactions": [
    {
      "baseFee": 1,
      "envelopeXdr": "<string>",
      "networkPassphrase": "<string>",
      "notes": "<string>",
      "routerContract": "<string>",
      "sourceAccount": "<string>",
      "latestLedger": 1,
      "minResourceFee": "<string>",
      "simulated": true
    }
  ]
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}

{
  "code": "<string>",
  "error": "unknown token_in 'INVALID-123'"
}