Integrating with Aquarius

Architecture overview, contract addresses, and integration paths for building on Aquarius

This section is for developers integrating Aquarius into a wallet, app, or trading bot. All guides come with fully functional code examples in Python and JavaScript, built on the Stellar SDK.

For the fastest start, the Quickstart executes a complete swap on testnet in about five minutes — no configuration needed.

Official SDKs

The SDKs wrap the full swap flow — routing, simulation, submission, retries, and typed errors:

Language	Package	Install
Python	aquarius-sdk	pip install aquarius-sdk
TypeScript / JavaScript	@aquariusdefi/sdk	npm install @aquariusdefi/sdk

The SDKs cover the full integration surface: swaps (exact-input and exact-output), liquidity deposits and withdrawals, reward claims, concentrated positions, and integrator fee collectors. The Quickstart and the code examples use them throughout; the raw API and contract flow each SDK call wraps is documented in the Reference section.

How Aquarius fits together

An integration touches up to three layers:

1. On-chain AMM — Soroban smart contracts. The AMM router is the single entry point for the classic operations: swaps (including multi-hop swap_chained), deposits, withdrawals, reward claims, and pool discovery. The router deploys and indexes the underlying pool contracts, so you rarely need to talk to a pool directly. The one exception is concentrated liquidity — positions there are managed by calling the pool contract itself.

2. Backend API — amm-api.aqua.network. A public REST API providing path finding and indexed pool data, fully documented at amm-api.aqua.network/api/schema/redoc. It is a convenience layer: the find-path endpoints return a ready-to-execute XDR swap chain, but execution always happens on-chain, and you can bypass the API entirely by querying pools through the router.

3. Your application — builds transactions with the Stellar SDK, simulates them against Soroban RPC, then signs and submits.

A typical swap looks like this:

Pool types

Pool type	Price formula	Swap fee tiers
Volatile	Constant product (x·y=k)	0.1% / 0.3% / 1%
Stable	Stableswap (amplified, for pegged assets)	0.01%–1%
Concentrated	Tick-based ranges (Uniswap v3 style)	0.1% / 0.3% / 1%

A share of every swap fee goes to liquidity providers and a share to the protocol; the split is configured on-chain and can be read from the router via get_protocol_fee_fraction().

Addresses & endpoints

All contract addresses, API base URLs, and RPC endpoints for both networks live in Addresses & networks — the single source of truth. The backend API endpoints and versioning are documented in the Backend API reference; integrations should use API version v2. Everything works on testnet too.

Choose your integration path

• Execute swaps — the most common integration (wallets, bots). The official SDKs cover it end to end; Executing swaps through optimal path documents the raw flow.

• Provide liquidity programmatically — Deposit, Withdraw, and Claim LP rewards.

• Monetize your integration — charge your own fee on swaps executed through your app.

• Concentrated liquidity positions — the dedicated contract interface reference and code examples.

• Read market data — Get pools info via smart contracts or the backend API (full endpoint reference).

Errors & slippage

Things every integration should handle:

• No path found. The find-path endpoints return HTTP 200 with success: false and zeroed fields when no route exists — always check the success flag.

• Slippage protection. Swaps take an out_min (exact-input) or max_in (exact-output) guard. If the pool can't satisfy it, the contract call fails with error 2006 OutMinNotSatisfied or 2020 InMaxNotSatisfied. For multi-hop swaps the guard is enforced end-to-end, not per hop. The code examples use 1% slippage — the same default as the Aquarius app (which offers 0.1% / 0.5% / 1%). Use tighter values for stable pairs, wider for illiquid markets.

• Token ordering. Token vectors passed to the router must be sorted by contract address, or the call fails with 2002 TokensNotSorted. The order_token_ids helper in Prerequisites & basics handles this.

• Trustlines. The receiving account must hold a trustline for any classic Stellar asset it receives.

The full table of contract error codes — including pool-pause states and concentrated-pool specifics — is in the Error codes reference.

Terminology: a pool is identified inside the router by its pool hash (a 32-byte value also called pool index in function signatures, derived from the pool type and fee tier). The pool's deployed contract address is a separate value — get_pools(tokens) returns the mapping between the two.

Support

Questions or stuck on an integration? Reach the team and other builders on Discord, or explore the source on GitHub.