> 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

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.

{% hint style="success" %}
For the fastest start, the [Quickstart](/developers/quickstart.md) executes a complete swap on testnet in about five minutes — no configuration needed.
{% endhint %}

## Official SDKs

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

| Language                | Package                                                                | Install                         |
| ----------------------- | ---------------------------------------------------------------------- | ------------------------------- |
| Python                  | [`aquarius-sdk`](https://pypi.org/project/aquarius-sdk/)               | `pip install aquarius-sdk`      |
| TypeScript / JavaScript | [`@aquariusdefi/sdk`](https://www.npmjs.com/package/@aquariusdefi/sdk) | `npm install @aquariusdefi/sdk` |

The SDKs currently cover swaps: quotes and execution in both exact-input and exact-output modes. The [Quickstart](/developers/quickstart.md) runs on them. For everything else — liquidity, rewards, pool data — the [code examples](/developers/code-examples.md) call the API and contracts directly and double as the reference for what the SDKs wrap.

## How Aquarius fits together

An integration touches up to three layers:

1. **On-chain AMM — Soroban smart contracts.** The [AMM router](/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](/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 providing path finding and indexed pool data, fully documented at [amm-api.aqua.network/api/schema/redoc](https://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](https://developers.stellar.org/docs/tools/sdks), simulates them against Soroban RPC, then signs and submits.

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](/developers/reference/addresses-and-networks.md) — the single source of truth. The backend API endpoints and versioning are documented in the [Backend API reference](/developers/reference/backend-api.md); integrations should use API version `v2`. Everything works on [testnet](/developers/testing-on-testnet.md) too.

## Choose your integration path

* **Execute swaps** — the most common integration (wallets, bots). The [official SDKs](#official-sdks) cover it end to end; [Executing swaps through optimal path](/developers/code-examples/executing-swaps-through-optimal-path.md) documents the raw flow.
* **Provide liquidity programmatically** — [Deposit](/developers/code-examples/deposit-liquidity.md), [Withdraw](/developers/code-examples/withdraw-liquidity.md), and [Claim LP rewards](/developers/code-examples/claim-lp-rewards.md).
* **Monetize your integration** — [charge your own fee on swaps](/developers/code-examples/add-fees-to-swap.md) executed through your app.
* **Concentrated liquidity positions** — the dedicated [contract interface reference](/developers/concentrated-liquidity/contract-interface-reference.md) and [code examples](/developers/concentrated-liquidity/managing-positions-code-examples.md).
* **Read market data** — [Get pools info](/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 `order_token_ids` helper in [Prerequisites & basics](/developers/code-examples/prerequisites-and-basics.md) handles this.
* **Trustlines.** The receiving account must hold a [trustline](/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](/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).