Title: Vestige legacy swap aggregator
Source: https://nodely.io/docs/vestige/aggregator/

# Vestige legacy swap aggregator

The aggregator routes a swap across Algorand DEX pools to get the best output, then builds the transactions for you to sign. It has the same four routes as Vestige’s `swap/v4` aggregator, with one difference: **the router fee goes to the Algorand fee sink, not to Nodely.**

<a id="the-router-fee"></a>

## The router fee

| ALGO side of the swap | Fee |
| --- | --- |
| Under $1,000 | 0.10 % (10 bps) |
| $1,000 and over | 0.12 % (12 bps) |
| ASA to ASA (no ALGO side) | None |

-   Every quote gives the fee in `fee_bps`, and `amount_out` is already net of it. On an ALGO input the fee comes off the input (`combo.amount_in` is `amount` minus the fee); on an ALGO output it comes off the output.
-   The [Nodely Router](https://nodely.io/docs/vestige/aggregator/#the-nodely-router) contract pays the fee to the fee sink, [`Y76M3MSY6DKBRHBL7C3NNDXGS5IIMQVQVUAB6MP4XEMMGVF2QWNPL226CA`](https://allo.info/account/Y76M3MSY6DKBRHBL7C3NNDXGS5IIMQVQVUAB6MP4XEMMGVF2QWNPL226CA), as an inner payment of your swap call. The payment is part of the atomic group you sign: you can check it before signing and see it on chain afterwards.
-   Nodely takes nothing else: no spread on the quote, no hidden fee in the minimum output, no token discount scheme, and no share of positive slippage: anything a route delivers above the quote is yours.

The fee sink collects Algorand’s transaction fees and pays block proposers. A swap fee paid into it funds the network’s validators.

<a id="flow"></a>

## Flow

1.  **Quote**: `GET /swap/v4` with the two assets and the amount.
2.  **Build**: `POST /swap/v4/transactions` with the quote as the body, your address and a slippage. You get one atomic group of unsigned transactions.
3.  **Sign and send**: sign the transactions whose `signers` holds your address and submit the whole group in order to any algod.

```js
import algosdk from "algosdk";

const API = "https://vestleg.api.nodely.io";
const algod = new algosdk.Algodv2("", "https://mainnet-api.4160.nodely.dev", "");
const account = algosdk.mnemonicToSecretKey(process.env.MNEMONIC);
const sender = account.addr.toString();

// 1. Quote: 100 ALGO (in microALGO) to USDC, fixed input
const quote = await fetch(
  `${API}/swap/v4?from_asa=0&to_asa=31566704&amount=100000000&mode=sef&address=${sender}`,
).then((r) => r.json());
console.log("USDC out:", quote.amount_out / 1e6, "fee bps:", quote.fee_bps);

// 2. Build: 0.5 % slippage
const res = await fetch(`${API}/swap/v4/transactions?sender=${sender}&slippage=0.005`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(quote),
});
if (!res.ok) throw new Error(JSON.stringify((await res.json()).detail)); // 409: quote again
const group = await res.json();

// 3. Sign and send, in order
const signed = group.map((t) => algosdk.decodeUnsignedTransaction(Buffer.from(t.txn, "base64")).signTxn(account.sk));
const { txid } = await algod.sendRawTransaction(signed).do();
await algosdk.waitForConfirmation(algod, txid, 4);
```

A wallet connector (for example `@txnlab/use-wallet`) can sign the same list: decode each `txn` and pass them all to the wallet’s `signTransactions`.

<a id="get-swapv4"></a>

## `GET /swap/v4`

| Parameter | Notes |
| --- | --- |
| `from_asa`, `to_asa` | Required. Asset ids, `0` for ALGO |
| `amount` | Required, in **base units** (microALGO for ALGO) |
| `mode` | Required. `sef`: fixed input, `amount` goes in. `sfe`: fixed output, `amount` comes out |
| `address` | Optional, the account that will swap. Lets the quote count the opt-ins it needs |
| `enabled_providers`, `disabled_providers` | Optional, comma-separated provider codes (below) |
| `denominating_asset_id` | For `asset_in_price` and `asset_out_price`, default `0` |

```json
{
  "mode": "sef", "amount": 100000000, "asset_in": 0, "asset_out": 31566704,
  "asset_in_price": 1, "asset_out_price": 12.5721408320605,
  "amount_out": 7930839, "network_fee": 3000, "price_impact": 0.0019, "fee_bps": 10,
  "combo": {
    "asset_in": 0, "asset_out": 31566704, "amount_in": 99900000, "amount_out": 7930839, "network_fee": 3000,
    "transactions": [
      { "asset_in": 0, "asset_out": 31566704, "amount_in": 99900000, "amount_out": 7930839, "network_fee": 3000,
        "swaps": [{ "provider": "PT", "bps": 100000000, "application_id": 2757488616, "amount_in": 99900000,
                    "amount_out": 7930839, "fee": 0.003, "network_fee": 2000 }] }
    ]
  },
  "single": { "...": "the best single path, same shape" }
}
```

-   `combo` splits the amount over up to 200 pieces across pools and paths of up to four hops; `single` is the best single path. `amount_out` is `combo`’s.
-   Each entry of `combo.transactions` is one hop between two assets. Its `swaps` are the pools of that hop, with their share in `bps` (100,000,000 = 100 %) and the pool’s own fee in `fee`.
-   `network_fee` is in microALGO.

Provider codes:

| Code | Venue | Code | Venue |
| --- | --- | --- | --- |
| `T3` | Tinyman 2.0 | `AF` | Algofi |
| `PT` | Pact | `AS` | Algofi NanoSwap (stable) |
| `PS` | Pact StableSwap | `H2` | Humble 2.0 |
| `PW` | Pact weighted | `FL` | Folks lending deposit and withdraw |
| `PC` | Pact concentrated liquidity | `ff…` | A pool of two Folks fAssets, routed between their underlying assets (for example `ffT3`) |
| `TA` | tALGO mint and burn | `XA` | xALGO mint and burn |

<a id="post-swapv4transactions"></a>

## `POST /swap/v4/transactions`

| Parameter | Notes |
| --- | --- |
| Body | Required. The `/swap/v4` answer, as received |
| `sender` | Required. The account that swaps |
| `slippage` | Required. A fraction: `0.01` = 1 %. The group fails on chain if the output would fall below `amount_out × (1 − slippage)` |
| `random_signer` | Accepted, as Vestige |

This route allows bursts of 20 requests per IP (2 per second sustained, as the rest of the API).

The answer is one atomic group, in order:

```json
[
  { "txn": "iqRhcmN2xCB9eitB…", "signers": ["2ZVUBZTE…"], "message": "Opt the router in to asset(s) [31566704]" },
  { "txn": "jKRhcGFhk8QENhyE…", "signers": ["2ZVUBZTE…"], "message": "Deposit 300000 of 0 into the router" },
  { "txn": "…", "signers": ["2ZVUBZTE…"], "message": "Swap 300000 of 0 for at least 23737 of 31566704 through the router (2 pool legs)" }
]
```

-   `txn` is an unsigned transaction, base64-encoded msgpack. `message` says what it does.
-   The group includes the opt-ins it needs: yours into the output asset, and the router’s into an asset it hasn’t held yet. The router’s minimum balance for a new asset (0.1 ALGO) is paid once, by the first account that swaps that asset through it.
-   **Every group is run through algod `simulate` before it’s returned.** If it would fail (not enough balance, a pool moved, a missing opt-in), you get `409` with the reason in `detail`, never a group that fails on chain. Quote again and retry.
-   When the quote as sent doesn’t fit one group of 16 transactions, the route is re-quoted to fit, and the first `message` says so. Check `message` before you sign if the exact route matters.

<a id="get-swapv4fee-and-get-swapv4history"></a>

## `GET /swap/v4/fee` and `GET /swap/v4/history`

`/swap/v4/fee` takes `address` and answers the same for every address:

```json
{"bps_fee":0,"token_amount":0,"token_liquidity_amount":0,"router_fee_bps":10,"router_fee_bps_large":12,"router_fee_large_from_usd":1000}
```

-   `bps_fee` keeps Vestige’s meaning: the share of output **above the quote** (positive slippage) the router keeps, in 1/10,000. Vestige’s aggregator app keeps `bps_fee × (received − expected) / 10000` of it (`8000`, 80 %, for a wallet without its token). The Nodely Router keeps none, so it’s `0`.
-   `router_fee_bps`, `router_fee_bps_large` and `router_fee_large_from_usd` are the Nodely Router fee, a share of the trade paid to the fee sink: 10 bps, and 12 bps from $1,000 of the ALGO side. A quote gives the tier that applies in `fee_bps`.

`/swap/v4/history` gives the swaps and volume through the Nodely Router per bin: `interval` (default 86400 seconds), `start`, `denominating_asset_id`.

<a id="the-nodely-router"></a>

## The Nodely Router

|  |  |
| --- | --- |
| Mainnet app | [3772077474](https://allo.info/application/3772077474) (“Nodely Router”) |
| What it does | Runs every pool leg of a route as an inner transaction of one `swap()` call, checks your minimum output once, on the total, and pays the router fee to the fee sink. Unused fee reserve is refunded in the same call |
| Venues it can run | Tinyman 2.0, Pact (constant product, stable, weighted, concentrated), Algofi and NanoSwap, Folks lending and Folks-wrapped pools, tALGO and xALGO |
| Humble | Routed only on its own, as a direct call outside the router: its contract must be alone in its group |
| Safety | A guardian key can pause swaps. The app is still being tuned and Nodely can update it; it will be locked against updates once it’s final |

The router lets a wide split route keep almost all of its quote. On 2026-11-15, plain groups of direct pool calls kept 78 to 99 % of wide quotes; through the router, 95 to 99 % is guaranteed at 1 % slippage.

If the router is paused, quotes and transactions still answer, with routes that don’t go through it and carry no Nodely fee.
