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.
1. Install the SDK
pip install "aquarius-sdk>=0.6.0"npm install "@aquariusdefi/sdk@>=0.6.0" @stellar/stellar-sdk@^17.4.02. 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:
from stellar_sdk import Keypair
from aquarius import AquariusClient, AquariusError, Asset, XLM
AQUA = Asset.classic("AQUA", "GAHPYWLK6YRN7CVYZOO4H3VDRZ7PVF5UJGLZCSPAEIKJE2XSWF5LAGER")
aqua = AquariusClient(network="testnet", signer=Keypair.random())
try:
aqua.fund_with_friendbot()
aqua.ensure_trustline(AQUA)
# 10 XLM in stroops (1 XLM = 10^7 stroops).
receipt = aqua.swap(XLM, AQUA, amount_in=100_000_000, slippage=0.01, retries=2)
except AquariusError as error:
if error.tx_hash:
print(f"Failed or unconfirmed transaction: {error.tx_hash}")
raise
print(f"Swap executed: received {receipt.amount_out / 10**7} AQUA")
print(f"Transaction: {receipt.tx_hash}")import { Keypair } from "@stellar/stellar-sdk";
import { AquariusClient, Asset, XLM } from "@aquariusdefi/sdk";
const AQUA = Asset.classic("AQUA", "GAHPYWLK6YRN7CVYZOO4H3VDRZ7PVF5UJGLZCSPAEIKJE2XSWF5LAGER");
const aqua = new AquariusClient({ network: "testnet", signer: Keypair.random() });
await aqua.fundWithFriendbot();
await aqua.ensureTrustline(AQUA);
// 10 XLM in stroops.
const receipt = await aqua.swap({
from: XLM, to: AQUA, amountIn: 100_000_000n, slippage: 0.01, retries: 2,
});
console.log(`Swap executed: received ${Number(receipt.amountOut) / 1e7} AQUA`);
console.log(`Transaction: ${receipt.txHash}`);The output reports the AQUA received and the confirmed transaction hash. The amount depends on pool liquidity when the swap executes.
3. What the script did
Friendbot created and funded a fresh testnet account. The SDK waited for Horizon and RPC to see the account before returning.
ensure_trustlineopened an AQUA trustline on the signer's account (required for any classic Stellar asset you want to receive).swaprequested a route from the Find Path API, simulated, signed, and submitted the swap through the AMM router with a 1% slippage guard.If a confirmed slippage error occurred, the SDK requested a fresh quote and retried, up to 2 times. It read the amount received from the confirmed transaction result.
The 1% guard applies to each fresh quote. A re-quote can have a different price from the first quote. Use quote followed by execute when a person must approve a particular quoted price. Other errors are returned to the caller; see Testing on testnet.
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.Quote before you swap — Executing swaps through optimal path shows
quoteandexecute, exact-output swaps, and how the route is found. For other languages, see Contract authorization.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.
Last updated