Executing swaps with provider fees

Execute swaps through your fee collector, charging your provider fee on each one.

Route a swap through your deployed fee collector and keep a fraction of the output. Pass a ProviderFeeConfig to any quote or swap: the SDK keeps the fee arithmetic exact (ceiling rounding, both amount modes), targets the collector with client-built authorization, and the collector pulls the tokens, takes your cut from the output, and drives the router itself.

This page uses the official SDKs (0.5.0 or later). The contract-level flow below covers other languages. Deploy a collector first — see Deploying a new fee collector.

Swap with your fee

The fee is fee_fraction / fee_denominator of the swap's output: with the denominator 10,000, fee_fraction=10 is 0.1% and fee_fraction=30 is 0.3%. The denominator must match the value your collector was deployed with, and fee_fraction must stay at or below its max_swap_fee_fraction:

Python

from stellar_sdk import Keypair
from aquarius import AquariusClient, Asset, ProviderFeeConfig, XLM

AQUA = Asset.classic("AQUA", "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA")

aqua = AquariusClient(network="mainnet", signer=Keypair.from_secret("S..."))

fee = ProviderFeeConfig(
    contract_id="C...",     # your deployed collector
    fee_fraction=10,        # 10 / 10_000 -> 0.1% of the output
    fee_denominator=10_000,
)

receipt = aqua.swap(XLM, AQUA, amount_in=10_0000000, provider_fee=fee, retries=3)
print(f"user received: {receipt.amount_out}")   # net of your fee

JavaScript

import { Keypair } from "@stellar/stellar-sdk";
import { AquariusClient, Asset, XLM } from "@aquariusdefi/sdk";

const AQUA = Asset.classic("AQUA", "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA");

const aqua = new AquariusClient({ network: "mainnet", signer: Keypair.fromSecret("S...") });

const fee = {
  contractId: "C...",     // your deployed collector
  feeFraction: 10,        // 10 / 10000 -> 0.1% of the output
  feeDenominator: 10_000,
};

const receipt = await aqua.swap({ from: XLM, to: AQUA, amountIn: 10_0000000n, providerFee: fee, retries: 3 });
console.log(`user received: ${receipt.amountOut}`);   // net of your fee

Both amount modes work. With amount_out the SDK quotes the gross amount the route must produce so the user still receives exactly the requested output after your fee.

If you attached to the collector with aqua.fee_collector(...), fee_config() builds the same configuration with the contract id filled in — see Claiming & swapping accumulated fees.

Send the output to a third party

Set recipient to deliver the net output to another address — it does not sign anything. If the recipient lacks a trustline for the output asset, the error names the recipient, not your signer:

Python

fee = ProviderFeeConfig(
    contract_id="C...",
    fee_fraction=10,
    fee_denominator=10_000,
    recipient="G...",       # receives the net output; no signature required
)

receipt = aqua.swap(XLM, AQUA, amount_in=10_0000000, provider_fee=fee)

JavaScript

const fee = {
  contractId: "C...",
  feeFraction: 10,
  feeDenominator: 10_000,
  recipient: "G...",       // receives the net output; no signature required
};

const receipt = await aqua.swap({ from: XLM, to: AQUA, amountIn: 10_0000000n, providerFee: fee });

Your cut accumulates on the collector contract in the output tokens of the swaps. Collect it with Claiming & swapping accumulated fees.

Contract-level flow (any language)

The complete flow against the collector contract directly — request a route from the Find Path API, build the transaction, and call the collector's swap_chained (or swap_chained_to with a recipient):

Python

from decimal import Decimal

import requests
from stellar_sdk import Asset, Keypair, Network, scval, Server, SorobanServer, TransactionBuilder
from stellar_sdk.xdr import SCVal, TransactionMeta, UInt128Parts

# =========================================
# Configuration & Setup
# =========================================

# This account must have at least 3 XLM and a trustline to AQUA.
user_secret_key = "SA..........."
keypair = Keypair.from_secret(user_secret_key)

# Input and output tokens
token_in = Asset.native()  # XLM
token_out = Asset("AQUA", "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA")

# If True, the swap behaves like strict-send: the amount of the sending asset is fixed.
# If False, the swap behaves like strict-receive: the amount of the receiving asset is fixed.
is_send = True
# Amount of 1 XLM or 1 AQUA in stroops (depending on is_send)
amount = 1_0000000
slippage = Decimal("0.005")  # .5% slippage
provider_fee = Decimal("0.003")  # .3% provider fee
provider_fee_bps_denominator = 10000  # 100 bps = 1% = 100 / 10000

# swap provider contract for AMM swaps on mainnet
# IMPORTANT: Replace with your deployed contract ID. This contract address is only for test purposes.
provider_swap_contract_id = "CDJCVXFIT2UIVNLC22OWCHABTWKXUSYYLPKKBLJW67ISMIWX56YJBGLS"

# Soroban and Horizon servers
soroban_server = SorobanServer("https://mainnet.sorobanrpc.com")
horizon_server = Server("https://horizon.stellar.org/")
network = Network.PUBLIC_NETWORK_PASSPHRASE

# AQUA AMM API endpoint
base_api = 'https://amm-api.aqua.network/api/external/v2'


# =========================================
# Utility Function
# =========================================

def u128_to_int(value: UInt128Parts) -> int:
    """Convert Uint128Parts to Python int."""
    return (value.hi.uint64 << 64) + value.lo.uint64


# =========================================
# Functions
# =========================================

def find_swap_path(base_api: str, token_in_address: str, token_out_address: str, amount: int, is_send: bool) -> (int, str):
    """
    Call the Find Path API to retrieve the swap chain and estimated amount.
    """
    print("Requesting swap path from AMM API...")
    data = {
        'token_in_address': token_in_address,
        'token_out_address': token_out_address,
        'amount': amount,
        'slippage': str(slippage),
        'provider_fee': str(provider_fee),
    }
    endpoint = '/find-path/' if is_send else '/find-path-strict-receive/'
    response = requests.post(f'{base_api}{endpoint}', json=data)
    swap_result = response.json()
    print(swap_result)
    """
        {
          'success': True,
          'swap_chain_xdr': 'AAAAEAAAAAEAAAABAAAAEAAAAAEAAAADAAAAEAAAAAEAAAACAAAAEgAAAAEltPzYWa7C+mNIQ4xImzw8EMmLbSG+T9PLMMtolT75dwAAABIAAAABKIUvaMGYSI40b7EhLtUCkFN2HMJPRTOS41OYIBsIJecAAAANAAAAILLgL8/KbJb4rVy9hOd4Snd7NtnJaiRZQCxPRYRiqrfwAAAAEgAAAAEohS9owZhIjjRvsSEu1QKQU3Ycwk9FM5LjU5ggGwgl5w==',
          'pools': [
            'CDE57N6XTUPBKYYDGQMXX7E7SLNOLFY3JEQB4MULSMR2AKTSAENGX2HC'
          ],
          'tokens': [
            'native',
            'AQUA:GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA'
          ],
          'amount': 3627808902,
          'amount_with_fee': 3627808002,
        }
    """

    if not swap_result.get('success', False):
        raise Exception("Failed to retrieve swap path from the API.")

    print("Swap path retrieved. Estimated amount:", swap_result['amount'])
    print("Estimated amount with fee:", swap_result['amount_with_fee'])
    return int(swap_result['amount_with_fee']), swap_result['swap_chain_xdr']


def execute_swap(
        network: str,
        soroban_rpc_server: SorobanServer,
        horizon_server: Server,
        keypair: Keypair,
        router_contract_id: str,
        token_in_address: str,
        amount: int,
        amount_with_slippage: int,
        swap_path: str,
        provider_fee_bps: int,
        is_send: bool,
) -> int:
    """
    Executes the chained swap transaction on Soroban and returns the final amount out.
    """
    print("Preparing and building swap transaction...")
    source_account = horizon_server.load_account(keypair.public_key)

    function_name = 'swap_chained' if is_send else 'swap_chained_strict_receive'

    # Build the transaction to invoke `swap_chained`
    tx = (
        TransactionBuilder(
            source_account=source_account,
            network_passphrase=network,
            base_fee=10000
        )
        .set_timeout(300)
        .append_invoke_contract_function_op(
            contract_id=router_contract_id,
            function_name=function_name,
            parameters=[
                scval.to_address(keypair.public_key),
                SCVal.from_xdr(swap_path),
                scval.to_address(token_in_address),
                scval.to_uint128(amount),
                scval.to_uint128(amount_with_slippage),
                scval.to_uint32(provider_fee_bps),
            ],
        )
        .build()
    )

    # Prepare transaction to get Soroban-specific data (footprint, etc.)
    print("Preparing transaction on Soroban...")
    prepared_tx = soroban_rpc_server.prepare_transaction(tx)

    # Sign the prepared transaction
    print("Signing transaction...")
    prepared_tx.sign(keypair)

    # Submit the transaction to Horizon
    print("Submitting transaction to Horizon...")
    submit_response = horizon_server.submit_transaction(prepared_tx)

    if not submit_response.get('successful', False):
        raise Exception("Transaction failed: " + str(submit_response))

    print("Transaction submitted successfully. Fetching result...")

    # Get the transaction result from Soroban server to access Soroban metadata
    tx_info = soroban_server.get_transaction(submit_response['id'])
    if not tx_info or not tx_info.result_meta_xdr:
        raise Exception("No transaction metadata found.")

    # Extract the result from the Soroban metadata
    transaction_meta = TransactionMeta.from_xdr(tx_info.result_meta_xdr)
    return_val = (transaction_meta.v4 if transaction_meta.v == 4 else transaction_meta.v3).soroban_meta.return_value
    final_amount = u128_to_int(return_val.u128)
    print("Swap executed successfully.")
    return final_amount


# =========================================
# Entry Point
# =========================================

print("Starting swap process...")
print(f"Swapping {token_in.code} for {token_out.code}...")

# 1. Find the swap path and estimated output
amount_with_slippage, swap_path_xdr = find_swap_path(
    base_api,
    token_in.contract_id(network),
    token_out.contract_id(network),
    amount,
    is_send,
)

# 2. Execute the swap
amount = execute_swap(
    network,
    soroban_server,
    horizon_server,
    keypair,
    provider_swap_contract_id,
    token_in.contract_id(network),
    amount,
    amount_with_slippage,
    swap_path_xdr,
    int(provider_fee * provider_fee_bps_denominator),  # Convert to basis points
    is_send,
)

print("Swap completed successfully!")

if is_send:
    print(f"Amount out: {amount / 10 ** 7} {token_out.code}")  # If it's strict-send, show output amount
else:
    print(f"Amount in: {amount / 10 ** 7} {token_in.code}")  # If it's strict-receive, show input amount

JavaScript

const {
    Horizon,
    Keypair,
    Asset,
    Networks,
    TransactionBuilder,
    xdr,
    nativeToScVal,
    Address,
    rpc,
    Operation,
} = require('@stellar/stellar-sdk');

// =========================================
// Configuration & Setup
// =========================================
// This account must have at least 3 XLM and a trustline to AQUA.
const userSecretKey = 'SA...........';
const keypair = Keypair.fromSecret(userSecretKey);

// Assets
const tokenIn = Asset.native();
const tokenOut = new Asset('AQUA', 'GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA');


// If true, the swap behaves like strict-send: the amount of the sending asset is fixed.
// If false, the swap behaves like strict-receive: the amount of the receiving asset is fixed.
const isSend = true;
// Amount of 1 XLM or 1 AQUA in stroops (depending on is_send)
const amount = 1_0000000;
const slippage = 0.005;   // 0.5%
const providerFee = 0.003; // 0.3%
const providerFeeBpsDenominator = 10000;

const providerSwapContractId = 'CDJCVXFIT2UIVNLC22OWCHABTWKXUSYYLPKKBLJW67ISMIWX56YJBGLS';

const sorobanServer = new rpc.Server('https://mainnet.sorobanrpc.com');
const horizonServer = new Horizon.Server('https://horizon.stellar.org');
const networkPassphrase = Networks.PUBLIC;

const baseApi = 'https://amm-api.aqua.network/api/external/v2';

// =========================================
// Utilities
// =========================================
function u128ToInt(value) {
    /**
     * Converts UInt128Parts from Stellar's XDR to a JavaScript number.
     *
     * @param {Object} value - UInt128Parts object from Stellar SDK, with `hi` and `lo` properties.
     * @returns {number|null} Corresponding JavaScript number, or null if the number is too large.
     */
    const result = (BigInt(value.hi()._value) << 64n) + BigInt(value.lo()._value);

    // Check if the result is within the safe integer range for JavaScript numbers
    if (result <= BigInt(Number.MAX_SAFE_INTEGER)) {
        return Number(result);
    } else {
        console.warn("Value exceeds JavaScript's safe integer range");
        return null;
    }
}

// =========================================
// API: Find Swap Path
// =========================================
// Call the Find Path API to retrieve the swap chain and estimated amount.
async function findSwapPath(tokenInAddress, tokenOutAddress, amount, isSend) {
    const data = {
        token_in_address: tokenInAddress,
        token_out_address: tokenOutAddress,
        amount: amount,
        slippage: slippage.toString(),
        provider_fee: providerFee.toString()
    };
    const endpoint = isSend ? '/find-path/' : '/find-path-strict-receive/';
    const response = await fetch(`${baseApi}${endpoint}`, {
        method: 'POST',
        body: JSON.stringify(data),
        headers: { 'Content-Type': 'application/json' }
    });

    const swapResult = await response.json();

    if (!swapResult.success) {
        throw new Error('Failed to retrieve swap path from the API.');
    }

    console.log('Swap path retrieved. Estimated amount:', swapResult.amount / 1e7);
    return {
        amountWithFee: parseInt(swapResult.amount_with_fee),
        swapPathXdr: swapResult.swap_chain_xdr
    };
}

// =========================================
// Soroban: Execute Swap Transaction
// =========================================
// Executes the chained swap transaction on Soroban and returns the final amount out.
async function executeSwap({
    keypair,
    routerContractId,
    tokenInAddress,
    amount,
    amountWithSlippage,
    swapPathXdr,
    providerFeeBps,
    isSend
}) {
    const account = await horizonServer.loadAccount(keypair.publicKey());
    const functionName = isSend ? 'swap_chained' : 'swap_chained_strict_receive';

    // Build the transaction to invoke `swap_chained`
    const tx = new TransactionBuilder(account, {
        fee: '10000',
        networkPassphrase
    })
        .setTimeout(300)
        .addOperation(
            Operation.invokeContractFunction({
                contract: routerContractId,
                function: functionName,
                args: [
                    nativeToScVal(new Address(keypair.publicKey())),
                    xdr.ScVal.fromXDR(swapPathXdr, 'base64'),
                    nativeToScVal(new Address(tokenInAddress)),
                    nativeToScVal(BigInt(amount), { type: 'u128' }),
                    nativeToScVal(BigInt(amountWithSlippage), { type: 'u128' }),
                    nativeToScVal(providerFeeBps, { type: 'u32' })
                ],
            })
        )
        .build();

    // Prepare transaction to get Soroban-specific data (footprint, etc.)
    const preparedTx = await sorobanServer.prepareTransaction(tx);
    // Sign the prepared transaction
    preparedTx.sign(keypair);

    // Submit the transaction to Horizon
    const submitResponse = await horizonServer.submitTransaction(preparedTx);

    if (!submitResponse.successful) {
        throw new Error('Transaction failed: ' + JSON.stringify(submitResponse));
    }

    // Get the transaction result from Soroban server to access Soroban metadata
    const txResult = await sorobanServer.getTransaction(submitResponse.id);
    const meta = txResult.resultMetaXdr;

    if (!meta) {
        throw new Error('No metadata returned from transaction.');
    }

    // Extract the result from the Soroban metadata
    const returnVal = meta.value().sorobanMeta().returnValue();
    const u128 = returnVal.value();

    return u128ToInt(u128);
}

// =========================================
// Main
// =========================================
(async () => {
    try {
        console.log(`Swapping ${tokenIn.code} for ${tokenOut.code}...`);

        const tokenInAddress = tokenIn.contractId(networkPassphrase);
        const tokenOutAddress= tokenOut.contractId(networkPassphrase);

        // 1. Get path & expected output with fees/slippage
        const { amountWithFee, swapPathXdr } = await findSwapPath(
            tokenInAddress,
            tokenOutAddress,
            amount,
            isSend
        );

        // 2. Execute Soroban swap
        const providerFeeBps = Math.round(providerFee * providerFeeBpsDenominator);
        const finalAmount = await executeSwap({
            keypair,
            routerContractId: providerSwapContractId,
            tokenInAddress,
            amount,
            amountWithSlippage: amountWithFee,
            swapPathXdr,
            providerFeeBps,
            isSend
        });

        console.log('Swap completed!');
        if (isSend) {
            console.log(`Amount out: ${finalAmount / 1e7} ${tokenOut.code}`);
        } else {
            console.log(`Amount in: ${finalAmount / 1e7} ${tokenIn.code}`);
        }
    } catch (err) {
        console.error('❌ Swap failed:', err.message || err);
    }
})();