Quickstart

Execute your first Aquarius swap in about five minutes — on testnet, with the official SDK and nothing to configure.

This page gets you from zero to a completed on-chain swap with the official Aquarius SDK. It runs on testnet, creates and funds its own throwaway account, and has no placeholders to fill in — install, run, and watch a swap execute.

Both scripts below are complete and runnable as-is — each was executed against testnet with the published packages before publishing, and the Python flow re-runs weekly in CI against the live testnet deployment.

Stellar testnet is wiped 2–4 times per year. Contract addresses persist across resets, but pools and balances are recreated — if the script fails right after a reset, the testnet stack may still be rebuilding. See Testing on testnet.

1. Install the SDK

Python

pip install aquarius-sdk

JavaScript

2. Run your first swap

The script funds a fresh testnet account with friendbot, adds an AQUA trustline, quotes the best route from 10 XLM to AQUA, and executes the swap on-chain. Save it as swap.py or swap.mjs and run it:

Python

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

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

aqua = AquariusClient(network="testnet", signer=Keypair.random())
aqua.fund_with_friendbot()
aqua.ensure_trustline(AQUA)

quote = aqua.quote(XLM, AQUA, amount_in=100_000_000)  # 10 XLM in stroops (1 XLM = 10^7 stroops)
print(f"Route found: expected output {quote.amount_out / 10**7} AQUA")

receipt = quote.execute()
print(f"Swap executed: received {receipt.amount_out / 10**7} AQUA")

JavaScript

Expected output:

Route found: expected output 2247.836633 AQUA
Swap executed: received 2247.836633 AQUA

3. What the script did

1. Friendbot created and funded a fresh testnet account — nothing to configure or protect.

2. ensure_trustline let the account hold AQUA (required for any classic Stellar asset you want to receive).

3. quote asked the Find Path API for the best route across the pools — the same call returns exact-output quotes when you pass amount_out instead.

4. execute simulated, signed, and submitted the swap through the AMM router, guarded by the quote's slippage limit (default 1%), and read the exact amount received from the result.

That one flow — route off-chain, execute on-chain — is the core of every Aquarius integration.

Next steps

• Understand the pieces — Integrating with Aquarius explains the router, pools, and API architecture, and lists the official SDKs.

• Go to mainnet — construct the client with network="mainnet" and a funded account's secret key.

• See the raw flow — Executing swaps through optimal path documents what the SDK wraps: the Find Path API call and the router invocation, step by step, for any language.

• Go deeper — Code examples covers liquidity provision, reading pool data, and charging integrator fees.

• If the script fails and the testnet page doesn't explain it, ask in Discord.