Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.0

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:

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

  1. Friendbot created and funded a fresh testnet account. The SDK waited for Horizon and RPC to see the account before returning.

  2. ensure_trustline opened an AQUA trustline on the signer's account (required for any classic Stellar asset you want to receive).

  3. swap requested a route from the Find Path API, simulated, signed, and submitted the swap through the AMM router with a 1% slippage guard.

  4. 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

Last updated