Prerequisites & basics

Dependencies, commonly used URLs, contract addresses and useful methods

The official SDKs bundle the constants and helpers on this page — integrations in Python or JavaScript can start from the Quickstart instead. This page serves integrations that call the API and contracts directly.

Prerequisites

Before executing scripts, ensure you have Stellar SDK installed:

Python

• Python 3.10+: The script is written in Python and requires Python version 3.10 or higher (required by current stellar-sdk releases).

• Stellar SDK: Install via pip:

pip install stellar-sdk

JavaScript

• Node 24: Run the JavaScript examples with Node version 24.

• Stellar SDK (v15 or newer — the same major version the Aquarius app runs on): Install via npm or yarn.

npm install @stellar/stellar-sdk

or

yarn add @stellar/stellar-sdk

Constants

Below are some API endpoints and contract addresses that will be used in other code examples.

For mainnet

Python

# The contract ID of the Aquarius AMM contract
router_contract_id = "CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK"
# Soroban RPC server address
soroban_rpc_server = "https://mainnet.sorobanrpc.com"
# Horizon server address
horizon_server = "https://horizon.stellar.org"
# Aquarius backend API URL
base_api = "https://amm-api.aqua.network/api/external/v2"

JavaScript

// The contract ID of the Aquarius AMM contract
const routerContractId = "CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK";
// Soroban RPC server address
const sorobanRpcServer = "https://mainnet.sorobanrpc.com";
// Horizon server address
const horizonServer = "https://horizon.stellar.org";
// Aquarius backend API URL
const baseApi = "https://amm-api.aqua.network/api/external/v2";

For testnet

Python

# The contract ID of the Aquarius AMM contract
# Address updated on February 2026 and should be valid across testnet resets.
router_contract_id = "CBCFTQSPDBAIZ6R6PJQKSQWKNKWH2QIV3I4J72SHWBIK3ADRRAM5A6GD"
# Soroban RPC server address
soroban_rpc_server = "https://soroban-testnet.stellar.org:443"
# Horizon server address
horizon_server = "https://horizon-testnet.stellar.org"
# Aquarius backend API URL
base_api = "https://amm-api-testnet.aqua.network/api/external/v2"

JavaScript

// The contract ID of the Aquarius AMM contract
// Address updated on February 2026 and should be valid across testnet resets.
const routerContractId = "CBCFTQSPDBAIZ6R6PJQKSQWKNKWH2QIV3I4J72SHWBIK3ADRRAM5A6GD";
// Soroban RPC server address
const sorobanRpcServer = "https://soroban-testnet.stellar.org:443";
// Horizon server address
const horizonServer = "https://horizon-testnet.stellar.org";
// Aquarius backend API URL
const baseApi = "https://amm-api-testnet.aqua.network/api/external/v2";

API versions: use v2. Version v1 remains available and is identical except for one endpoint — v2's find-path-strict-receive correctly accounts for provider fees in the required input amount. No API key is currently required.

Transaction fees

The fee passed to TransactionBuilder is your inclusion-fee bid in stroops — the resource fees for Soroban execution are calculated during simulation and added automatically by prepare_transaction / prepareTransaction. Any bid at or above the network minimum (100 stroops) is accepted; the examples use higher values, which helps transactions get included during network surge pricing without changing what you pay in quiet conditions.

Helper functions

Common utility methods that will be used in other code examples.

Get asset contract ID

To interact with any Soroban assets, you need their smart contract address.

This code snippet demonstrates how to retrieve the contract address of an asset on the Stellar network. The code uses the PUBLIC network by default, but you can switch to the desired network (for example, TESTNET).

Python

from stellar_sdk import Asset, Network

# Create the native asset
asset = Asset.native()
# Or create a custom asset
# asset = Asset("AQUA", "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA")

# Retrieve the contract ID for the PUBLIC network
contract_id = asset.contract_id(Network.PUBLIC_NETWORK_PASSPHRASE)

print(contract_id)
# Example output:
# "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA"

JavaScript

const StellarSdk = require('@stellar/stellar-sdk');

// Create the native asset
const asset = StellarSdk.Asset.native();
// Or create a custom asset
// const asset = new StellarSdk.Asset('AQUA', 'GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA');

// Retrieve the contract ID for the PUBLIC network
const contractId = asset.contractId(StellarSdk.Networks.PUBLIC);

console.log(contractId);
// console.log example
// "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA"

Get pool contract ID and pool hash

To interact with an Aquarius pool (for example, make deposits or direct swaps), you need the address of the pool contract.

One option to find the pool address is to refer to the pool page on Aquarius website, please see below:

Example of pool contract address, click to copy.

To retrieve this information programmatically, see Get pools info.

Order tokens IDs

Most of the time, if an array of token IDs needs to be passed as arguments in a contract call, they should be sorted.

Python

def order_token_ids(tokens: List[xdr.SCVal]) -> List[xdr.SCVal]:
   """
   Orders token IDs based on their contract ID to maintain consistency.

   Args:
       tokens (List[xdr.SCVal]): List of token addresses as SCVal objects.

   Returns:
       List[xdr.SCVal]: Ordered list of token SCVal objects.
   """
   return sorted(tokens, key=lambda token: int(token.address.contract_id.hash.hex(), 16))

JavaScript

function orderTokensIds(tokensIds) {
    /**
     * Orders token IDs based on their contract ID to maintain consistency.
     *
     * @param {Array} tokensIds - List of token addresses as SCVal objects.
     * @returns {Array} Ordered list of token SCVal objects.
     */
    return tokensIds.sort((a, b) => {
        const aHash = BigInt('0x' + a.address().contractId().toString('hex'));
        const bHash = BigInt('0x' + b.address().contractId().toString('hex'));

        // Compare BigInts directly without converting to number
        if (aHash < bHash) return -1;
        if (aHash > bHash) return 1;
        return 0;
    });
}

Data conversion utilities

Here are methods and code snippets for converting data between basic types and ScVal (Smart Contract Value).

Python

from stellar_sdk import Address, scval

# ================
# Basic => ScVal
# ================

# Contract Id To ScVal
contract_id = "C..."
contract_id_scval = scval.to_address(contract_id)

# Array To ScVal
scval.to_vec([contract_id_scval, contract_id_scval])

# Public Key To ScVal
public_key = "G..."
public_key_scval = scval.to_address(public_key)

# Number To Uint32 ScVal
number_u32_scval = scval.to_uint32(1_000_000)


# Number To Uint128 ScVal
number_u128_scval = scval.to_uint128(1_000_000)

# Hash To ScVal 
pool_hash = "a1b2...."
pool_hash_scval = scval.to_bytes(bytes.fromhex(pool_hash))

# ================
#  ScVal => Basic
# ================

def u128_to_int(value: UInt128Parts) -> int:
   """
   Converts UInt128Parts from Stellar's XDR to a Python integer.

   Args:
       value (UInt128Parts): UInt128Parts object from Stellar SDK.

   Returns:
       int: Corresponding Python integer.
   """
   return int(value.hi.uint64 << 64) + value.lo.uint64

JavaScript

const StellarSdk = require('@stellar/stellar-sdk');
const { Address, StrKey, XdrLargeInt, xdr } = StellarSdk;

// ================
// Basic => ScVal
// ================

function contractIdToScVal(contractId) {
    /**
     * Converts a contract ID to a Stellar SCVal (Smart Contract Value) format.
     *
     * @param {string} contractId - The contract ID to convert.
     * @returns {StellarSdk.xdr.ScVal} - The SCVal representation of the contract ID.
     *
     * @throws {Error} Throws an error if the contract ID is invalid or cannot be decoded.
     */
    return Address.contract(StrKey.decodeContract(contractId)).toScVal();
}

function arrayToScVal(array) {
    /**
     * Converts an array of ScVal objects into a single ScVal vector.
     *
     * @param {StellarSdk.xdr.ScVal[]} array - An array of ScVal objects to be converted into a vector.
     * @returns {StellarSdk.xdr.ScVal} A ScVal object representing the vector.
    */
    return xdr.ScVal.scvVec(array);
}


function publicKeyToScVal(pubkey) {
    /*
     * Converts a Stellar public key string into an ScVal address.
     *
     * @param {string} pubkey - The Stellar public key to be converted.
     * @returns {StellarSdk.xdr.ScVal} An ScVal object representing the address derived from the public key.
    */
    return xdr.ScVal.scvAddress(Address.fromString(pubkey).toScAddress());
}

function numberToUint32(number) {
    /**
     * Converts a number to an ScVal representing a 32-bit unsigned integer (Uint32).
     *
     * @param {number} number - The number to be converted. Must be a non-negative integer within the range of Uint32 (0 to 2^32 - 1).
     * @returns {StellarSdk.xdr.ScVal} An ScVal object representing the 32-bit unsigned integer.
    */
    return xdr.ScVal.scvU32(number);
}

function numberToUint128(number) {
    /**
     * Converts a number to an ScVal representing a 128-bit unsigned integer (Uint128).
     *
     * @param {number} number - The number to be converted. Must be a non-negative value that fits within the range of Uint128.
     * @returns {StellarSdk.xdr.ScVal} An ScVal object representing the 128-bit unsigned integer.
    */
    return new XdrLargeInt(
        'u128',
         number.toFixed(),
    ).toU128();
}

function bufferToScVal(buffer) {
    /**
     * Converts a Buffer object into an ScVal representing a byte array.
     *
     * @param {Buffer} buffer - The Buffer object containing the byte data to be converted.
     * @returns {StellarSdk.xdr.ScVal} An ScVal object representing the byte array.
    */
    return xdr.ScVal.scvBytes(buffer);
}


function hashToScVal(hash) {
    /**
     * Converts a hexadecimal hash string into an ScVal representing a byte array.
     *
     * @param {string} hash - The hash string in hexadecimal format to be converted.
     * @returns {StellarSdk.xdr.ScVal} An ScVal object representing the byte array derived from the hash.
    */
    return xdr.ScVal.scvBytes(Buffer.from(hash, 'hex'));
}

// ================
// SvVal => Basic
// ================

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;
    }
}