> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soroswap.finance/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Soroswap Aggregator API: base URL https://api.soroswap.finance, pick the network with ?network=mainnet or ?network=testnet (omitted means mainnet).
> Auth: Authorization: Bearer sk_... on every call. Get a key at https://console.soroswap.finance/register. A missing or invalid key returns 401 with code and registerUrl (POST /send returns 403 instead); an expired JWT or a missing role returns 403. Free plan 1 request/s; see https://docs.soroswap.finance/api/plans.md.
> Flow: POST /quote (assetIn, assetOut as C... contract addresses, amount as an integer string in the smallest unit, tradeType, protocols) -> POST /quote/build with the unchanged quote and from -> the user signs the XDR -> POST /send. Build right after quoting: a Soroban XDR is valid for 180 seconds. Submit it as is, never re-simulate it.
> Partner id: every account has one (9 hex chars, permanent). Read partnerId from GET /partner, or in the console at https://console.soroswap.finance under Fees & payouts. The partner fee itself is switched on by Soroswap; see https://docs.soroswap.finance/api/fees.md.
> AI tools: docs MCP at https://docs.soroswap.finance/mcp (claude mcp add --transport http soroswap-docs https://docs.soroswap.finance/mcp), skill with npx skills add https://docs.soroswap.finance. Other clients: https://docs.soroswap.finance/api/build-with-ai.md.
> Units and Stellar pitfalls: https://docs.soroswap.finance/api/stellar-gotchas.md. Errors and retries: https://docs.soroswap.finance/api/errors.md.

# Cross-Contract Integration

> Call Soroswap Aggregator v3 from your own Soroban contract: client import, route building, the token authorization, and a verified mainnet example.

Use this when **your contract** calls the aggregator: a router, a vault or an intent settler.
If your backend just needs a transaction for a user to sign, use the API's `/quote/build` instead and skip this page.

The full contract reference is in [Aggregator v3](https://docs.soroswap.finance/aggregator/technical-reference/contracts/aggregator-v3.md).

## 1. Import the client

The WASM on chain is the interface. Fetch it once and import it:

```bash theme={null}
stellar contract fetch --id CARVQXFP4JF5ELLXUMQ6DALR346YVGBMQOHB4ENA7SSVXAYABXLBDDC4 \
  --network mainnet -o aggregator_v3.wasm
```

```rust theme={null}
mod aggregator {
    soroban_sdk::contractimport!(file = "aggregator_v3.wasm");
}
use aggregator::{Hop, Route, SushiHop};
```

`contractimport!` generates `aggregator::Client` and every wire type (`Route`, `Hop`, `SoroswapHop`, `AquaHop`, `SushiHop`, `CometHop`, `PhoenixHop`, `Partner`).

## 2. Build the routes

A route names the pools, in order, that take `token_in` to `token_out`, like the single-pool example below.

The route amounts must add up to `amount_in - fee`, with `fee = floor(amount_in * bps / 10000)`.

## 3. Authorize the token pull, then call

The aggregator pulls `token_in` from `user` with `transfer`. When `user` is your contract, that `transfer` happens one call below your own, so your contract must authorize it explicitly:

```rust theme={null}
use soroban_sdk::{
    auth::{ContractContext, InvokerContractAuthEntry, SubContractInvocation},
    vec, Address, Env, IntoVal, Symbol,
};

let me = env.current_contract_address();

env.authorize_as_current_contract(vec![
    &env,
    InvokerContractAuthEntry::Contract(SubContractInvocation {
        context: ContractContext {
            contract: token_in.clone(),
            fn_name: Symbol::new(&env, "transfer"),
            args: (me.clone(), aggregator_id.clone(), amount_in).into_val(&env),
        },
        sub_invocations: vec![&env],
    }),
]);

let delivered: i128 = aggregator::Client::new(&env, &aggregator_id).swap_exact_in(
    &me,          // user: the tokens come from, and go back to, this contract
    &token_in,
    &amount_in,   // gross, fee included
    &token_out,
    &min_out,
    &routes,
    &None,        // or Some(Partner { id, bps }) if you have a partner rate
);
```

`delivered` is credited to `me`. Forward it wherever your contract needs it.

## Example: USDC to deJTRSY through a SushiSwap V3 pool

This contract was deployed and run on mainnet on 2026-10-08:

```rust theme={null}
#![no_std]
use soroban_sdk::{
    auth::{ContractContext, InvokerContractAuthEntry, SubContractInvocation},
    contract, contractimpl, vec, Address, Env, IntoVal, Symbol,
};

mod aggregator {
    soroban_sdk::contractimport!(file = "aggregator_v3.wasm");
}
use aggregator::{Hop, Route, SushiHop};

#[contract]
pub struct MyRouter;

#[contractimpl]
impl MyRouter {
    pub fn swap_via_sushi(
        e: Env,
        aggregator_id: Address,
        pool: Address,
        token_in: Address,
        token_out: Address,
        zero_for_one: bool,
        amount_in: i128,
        share: i128, // amount_in - fee
        min_out: i128,
    ) -> i128 {
        let me = e.current_contract_address();
        let routes = vec![
            &e,
            Route {
                amount_in: share,
                hops: vec![
                    &e,
                    Hop::Sushi(SushiHop {
                        pool,
                        token_in: token_in.clone(),
                        token_out: token_out.clone(),
                        zero_for_one,
                    }),
                ],
            },
        ];
        e.authorize_as_current_contract(vec![
            &e,
            InvokerContractAuthEntry::Contract(SubContractInvocation {
                context: ContractContext {
                    contract: token_in.clone(),
                    fn_name: Symbol::new(&e, "transfer"),
                    args: (me.clone(), aggregator_id.clone(), amount_in).into_val(&e),
                },
                sub_invocations: vec![&e],
            }),
        ]);
        aggregator::Client::new(&e, &aggregator_id).swap_exact_in(
            &me, &token_in, &amount_in, &token_out, &min_out, &routes, &None,
        )
    }
}
```

The call used these values:

| Argument | Value |
| - | - |
| `pool` | `CDMJRRH5MAJLB7T5SQAWQOOL7UJ3BABGTURSVKIE6AEDSXESDDJIBVCT` (deJTRSY/USDC, fee tier 500) |
| `token_in` | USDC `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75` (token1) |
| `token_out` | deJTRSY `CBI7UCH5KGSVQRO5H4SUCZUTZABCITZLRHQQZTWL2TK4RZ72TAR6IHRV` (token0) |
| `zero_for_one` | `false`, because USDC is not `token0` |
| `amount_in` / `share` | `5000000` / `4995000` (0.5 USDC, minus the 10 bps fee) |

The swap delivered 0.4865 deJTRSY to the contract. See [the transaction](https://stellar.expert/explorer/public/tx/95ad366282a9ee0ac9adcbe6c55a617dcc458dd4c9742b985143be92891dbc15).

The same swap from an account, with the user signing (no `authorize_as_current_contract` needed), in both directions:
[USDC → deJTRSY](https://stellar.expert/explorer/public/tx/2e90c3d95b1d3ac5dd1cabaae4838e6a93473e74c49218a6598f01a6d602325e) and
[deJTRSY → USDC](https://stellar.expert/explorer/public/tx/83b710e9e24a5a7ce9b9937f61c5126aa23a68aa480bf9d85b1e334101a0a132).

## Checklist

* Call `CARVQXFP4JF5ELLXUMQ6DALR346YVGBMQOHB4ENA7SSVXAYABXLBDDC4`, not the deprecated `CAYP3U…` aggregator.
* Make the route amounts add up to `amount_in - fee`, with the same `partner` the quote was priced with.
* Set `zero_for_one = (token_in == pool.token0())` on every Sushi hop.
* Sort each Aquarius step's token set by `Address` order, not string order.
* When `user` is a contract, authorize `token_in.transfer(user, aggregator, amount_in)`.
* Set `min_out` from your own slippage tolerance. It is the only price guarantee: the aggregator calls each venue with no real per-hop minimum (0 or 1, or none for SushiSwap and Phoenix) and checks only the total at the end.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.