> For the complete documentation index, see [llms.txt](https://docs.aqua.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aqua.network/developers/integrating-with-aquarius.md).

# 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 official Aquarius SDKs.

{% hint style="success" %}
Start with the [Quickstart](https://docs.aqua.network/developers/quickstart.md) to execute a testnet swap.
{% endhint %}

## Official SDKs

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

| Language                | Package                                                                | Requires                                                                            | Install                                                                |
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Python                  | [`aquarius-sdk`](https://pypi.org/project/aquarius-sdk/)               | Python 3.10 or later; installs `stellar-sdk` 17                                     | `pip install "aquarius-sdk>=0.6.0"`                                    |
| TypeScript / JavaScript | [`@aquariusdefi/sdk`](https://www.npmjs.com/package/@aquariusdefi/sdk) | Node.js 22.12 or later; peer dependency `@stellar/stellar-sdk` 17.4 or a later 17.x | `npm install "@aquariusdefi/sdk@>=0.6.0" @stellar/stellar-sdk@^17.4.0` |

Both SDKs cover swaps (exact-input and exact-output), liquidity deposits and withdrawals, reward claims, concentrated positions (beta), integrator fee collectors, and unsigned swap transactions for signing in an external wallet. The JavaScript SDK also covers pool creation, scheduling and claiming [Pool Incentives](https://docs.aqua.network/for-projects/pool-incentives.md), batch reads, claims across several pools under one signature, and an unsigned build of every write, including the restore transaction for archived contract state. The [Quickstart](https://docs.aqua.network/developers/quickstart.md) and the [code examples](https://docs.aqua.network/developers/code-examples.md) use them throughout; the API and contract calls each SDK method wraps, with the authorization each call needs, are documented in the [Reference](https://docs.aqua.network/developers/reference.md) section.

## How Aquarius fits together

An integration touches up to three layers:

1. **On-chain AMM — Soroban smart contracts.** The [AMM router](https://docs.aqua.network/developers/reference/router-and-pool-contracts.md) 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](https://docs.aqua.network/developers/concentrated-liquidity.md) — positions there are managed by calling the pool contract itself.
2. **Backend API — `amm-api.aqua.network`.** A public REST API for path finding and indexed pool data, with an [OpenAPI reference](https://amm-api.aqua.network/api/schema/redoc/). The find-path endpoints return a swap route as an XDR-encoded swap chain; you still build, sign, and submit the router call on-chain. You can skip the API and query pools through the router instead.
3. **Your application** — builds transactions with the [official SDKs](#official-sdks), which simulate them against Soroban RPC, sign, and submit. In other languages, build each call's authorization yourself as described in [Contract authorization](https://docs.aqua.network/developers/reference/contract-authorization.md).

A typical swap looks like this:

```mermaid
sequenceDiagram
    participant App as Your app
    participant API as Find Path API (v2)
    participant RPC as Soroban RPC
    participant Router as AMM router
    App->>API: POST /find-path with token in, token out, amount
    API-->>App: swap_chain_xdr, route, estimated amounts
    App->>RPC: simulate swap_chained(swaps_chain, in_amount, out_min)
    RPC-->>App: resource footprint and expected result
    App->>Router: sign and submit the transaction
    Note over Router: executes the hops across pools (up to 4)
    Router-->>App: amount received
```

## 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](https://docs.aqua.network/developers/reference/addresses-and-networks.md) — the single source of truth. The backend API endpoints and versioning are documented in the [Backend API reference](https://docs.aqua.network/developers/reference/backend-api.md); integrations should use API version `v2`. A separate [testnet deployment](https://docs.aqua.network/developers/testing-on-testnet.md) uses its own addresses.

## Choose your integration path

* **Execute swaps** — the most common integration (wallets, bots). [Executing swaps through optimal path](https://docs.aqua.network/developers/code-examples/executing-swaps-through-optimal-path.md) covers exact-input and exact-output swaps with the [official SDKs](#official-sdks).
* **Provide liquidity programmatically** — [Deposit](https://docs.aqua.network/developers/code-examples/deposit-liquidity.md), [Withdraw](https://docs.aqua.network/developers/code-examples/withdraw-liquidity.md), and [Claim LP rewards](https://docs.aqua.network/developers/code-examples/claim-lp-rewards.md).
* **Monetize your integration** — [charge your own fee on swaps](https://docs.aqua.network/developers/code-examples/add-fees-to-swap.md) executed through your app.
* **Concentrated liquidity positions** — the dedicated [contract interface reference](https://docs.aqua.network/developers/concentrated-liquidity/contract-interface-reference.md) and [code examples](https://docs.aqua.network/developers/concentrated-liquidity/managing-positions-code-examples.md).
* **Read market data** — [Get pools info](https://docs.aqua.network/developers/code-examples/get-pools-info.md) via smart contracts or the backend API ([full endpoint reference](https://amm-api.aqua.network/api/schema/redoc/)).

## 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 SDKs sort them for you; the rule is in [Token ordering](https://docs.aqua.network/developers/reference/router-and-pool-contracts.md#token-ordering).
* **Trustlines.** The receiving account must hold a [trustline](https://docs.aqua.network/ecosystem-overview/stellar-essentials.md) 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](https://docs.aqua.network/developers/reference/error-codes.md).

{% hint style="info" %}
**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.
{% endhint %}

## Support

Questions or stuck on an integration? Reach the team and other builders on [Discord](https://discord.gg/sgzFscHp4C), or explore the source on [GitHub](https://github.com/AquariusDeFi).
