Swap aggregator ABI

The swap aggregator is the on-chain router that executes swap routes. Controller strategies call it, and you can call it directly — it is not restricted to protocol use.

This page documents the contract. For the off-chain quote service that produces the route bytes — the HTTP API, token coverage, and prepared transaction envelopes — see Stellar Aggregator. You will normally use both: the service builds the payload, this contract executes it.

The lending protocol treats this contract as untrusted. The controller grants it authority for one stated input amount, ignores whatever it returns, and settles on measured balance deltas instead. It is also not owned by governance — it has its own owner and its own two-step ownership transfer.

The one entry point that matters

execute_strategy(sender: Address, total_in: i128, swap_xdr: Bytes) -> i128

It decodes swap_xdr as a StrategyPayload, pulls total_in from sender, runs any LP burn, then the swap paths, then any LP mint, applies fees, enforces the minimum output, and returns the delivered amount. Anyone may call it. sender authorizes the pull. A payload that fails to decode raises #13 InvalidRouteXdr. The payload’s shape — two registries plus a packed instruction stream — is documented in Strategies.

Slippage is enforced here, not by the controller. Your minimum output lives inside the payload bytes, and execute_strategy is the only thing that checks it. Falling short raises #5 SlippageExceeded. Build that floor correctly in your quote — nothing downstream will catch a bad price for you.

Fees

Two fees can apply, both in basis points, both capped at FEE_CAP = 1000 (10%). Exceeding the cap raises #21 FeeTooHigh.

Fee	Set by	Paid to
Static fee	Contract owner, via `set_static_fee`	The contract owner’s fee bucket
Referral fee	Contract owner, via `add_referral` / `set_referral_fee`	That referral’s configured owner

A payload carries a referral id in its header (u32, where 0 means none). Fees accrue into per-token buckets and are claimed separately — they are not swept into the swap output.

Claiming fees

Function	Auth	Notes
`claim_referral_fees(id, tokens)`	Anyone	Pays that referral’s accrued balances to its configured owner, not to the caller. The only claim path that is not owner-gated.
`claim_admin_fees(recipient, tokens)`	Owner only	Pays the static-fee bucket to `recipient`.

claim_referral_fees being permissionless is safe by construction: the recipient is read from stored referral config, so calling it on someone else’s behalf just pays them. You cannot redirect it.

Owner-only administration

All of these carry #[only_owner].

Function	Purpose
`set_static_fee(fee_bps)`	Sets the protocol-wide static fee. Capped at 1000 bps.
`add_to_whitelist(token)` / `remove_from_whitelist(token)`	Manages the token whitelist.
`add_referral(owner, fee_bps) -> u64`	Registers a referral and returns its id. Capped at 1000 bps.
`set_referral_fee(id, fee_bps)`	Changes a referral’s rate.
`set_referral_active(id, active)`	Enables or disables a referral.
`set_referral_owner(id, new_owner)`	Re-points where that referral’s fees go.
`claim_admin_fees(recipient, tokens)`	Pays out the static-fee bucket.
`sweep_balance(recipient, tokens)`	Recovers stray token balances. Leaves fee buckets intact.
`upgrade(new_wasm_hash)`	Replaces the contract Wasm.

Ownership is the standard two-step: transfer_ownership(new_owner, live_until_ledger), then accept_ownership() by the incoming owner. get_owner() returns None if ownership was renounced or never set.

Open reads

Function	Returns
`admin() -> Address`	The configured admin.
`get_owner() -> Option<Address>`	Current owner, or `None`.
`static_fee_bps() -> u32`	The static fee.
`referral(id) -> Option<ReferralConfig>`	A referral’s owner, rate, and active flag.
`referral_counter() -> u64`	How many referrals have been registered.
`is_whitelisted(token) -> bool`	Whitelist membership.
`whitelisted_tokens() -> Vec<Address>`	The full whitelist.
`admin_fee_balance(token) -> i128`	Unclaimed static-fee balance for one token.
`referral_fee_balance(id, token) -> i128`	Unclaimed referral balance for one token.

Error codes

This contract uses its own error enum, unrelated to the lending protocol’s codes. A #5 here is not a #5 from the controller.

Code	Name	Meaning
`1`	`EmptyBatch`	The route contained no instructions.
`3`	`InvalidAmount`	A declared amount is zero or negative.
`4`	`BrokenTokenChain`	One hop’s output token is not the next hop’s input.
`5`	`SlippageExceeded`	Delivered output fell below the payload’s minimum.
`7`	`ZeroOutput`	The route produced nothing.
`9`	`IntegerOverflow`	Arithmetic overflowed.
`11`	`ZeroSplitPpm`	A split weight was zero.
`12`	`SplitPpmMismatch`	Split weights do not sum to `1_000_000`.
`13`	`InvalidRouteXdr`	`swap_xdr` failed to decode as a `StrategyPayload`.
`20`	`NotAdmin`	Caller is not the admin.
`21`	`FeeTooHigh`	A fee exceeds `FEE_CAP = 1000` bps.
`22`	`ReferralNotFound`	No referral registered under that id.
`25`	`SameToken`	A hop’s input and output token are the same.
`26`	`LpTokenMismatch`	The LP share token does not match the pool.
`27`	`MinSharesNotMet`	An LP mint produced fewer shares than required.
`28`	`MinAmountsNotMet`	An LP burn returned less than required.
`29`	`ExcessiveResidual`	Too much input was left unspent.
`30`	`InternalInvariant`	An internal invariant failed. Report it.

Strategies

How controller strategies call this contract, and the payload layout.

Stellar Aggregator

The quote service that builds the route bytes.

Security model

Why the controller treats this contract as untrusted.

Addresses

Deployed swap-aggregator addresses per network.

Start here

Concepts

Integration guides

Reference

Operations

The one entry point that matters

Fees

Claiming fees

Owner-only administration

Open reads

Error codes

Next

Strategies

Stellar Aggregator

Security model

Addresses

​The one entry point that matters

​Fees

​Claiming fees

​Owner-only administration

​Open reads

​Error codes

​Next

Strategies

Stellar Aggregator

Security model

Addresses

The one entry point that matters

Fees

Claiming fees

Owner-only administration

Open reads

Error codes

Next