Multi-hop Routing
Overview
When there is no pool for the pair you want, or a better price is available through another asset, the Router swaps through several pools in one transaction. Hops execute one after the other; the last hop sends the ask asset to you.
Two router versions are live on each chain. Router 2.0 is the recommended one and is what this page documents.
| Chain | Router 2.0.0 (recommended) | Router 1.3.1 |
|---|---|---|
| Terra | terra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesf | terra18plp90j0zd596zt3zdsf0w9vvk5ukwlwzwkksxv9mdu8rscat9sqndk5qz |
| Neutron | neutron1xuh7nqt486gkvkxdwt773fzs5uptxy0ylzehm3spq7rx8r2kaspqzu0hv6 | neutron1rwj6mfxzzrwskur73v326xwuff52vygqk73lr7azkehnfzz5f5wskwekf4 |
What changed in Router 2.0:
pool_swaphops. Besidesastro_swap(the factory looks up the pool for the asset pair), a hop can name the pool by address. This lets a route use pools the factory doesn't know about, such as the USDC transmuter on Terra.minimum_receiveis required and must be greater than zero. It is the only price check: the pools' own spread checks are turned off on every hop, and there is nomax_spreadparameter.- Nested routes are refused. A route can't start while another route is running (
A swap route is already in progress). - A route has at most 50 hops, and each hop's offer asset must be the previous hop's ask asset.
Router 1.x keeps its old API (astro_swap and native_swap hops, optional minimum_receive and max_spread) and can't be migrated to 2.x. Existing integrations keep working; new integrations should use 2.0.
Swap Operations
A route is a list of SwapOperation values.
astro_swap swaps in the factory's pool for this asset pair:
_14{_14 "astro_swap": {_14 "offer_asset_info": {_14 "native_token": {_14 "denom": "uluna"_14 }_14 },_14 "ask_asset_info": {_14 "native_token": {_14 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_14 }_14 }_14 }_14}
pool_swap swaps in the pool at pool_addr. The router checks that the pool's pair query reports this address and both assets:
_15{_15 "pool_swap": {_15 "pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",_15 "offer_asset_info": {_15 "native_token": {_15 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_15 }_15 },_15 "ask_asset_info": {_15 "native_token": {_15 "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"_15 }_15 }_15 }_15}
pool_swap accepts any address. The pair check catches mistyped routes, but it can't prove that a contract is a genuine Astroport pool. Build pool_swap hops only from pools you have verified, for example from the Contract Addresses page or the factory's pairs query.
Example Route
The examples below swap 10 LUNA into USDC.inj on Terra in two hops:
- LUNA to USDC (Noble) in the LUNA/USDC pool, found by the factory (
astro_swap). - USDC (Noble) to USDC.inj in the USDC transmuter, given by address (
pool_swap).
| Asset | Denom on Terra |
|---|---|
| LUNA | uluna |
| USDC (Noble) | ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB |
| USDC.inj | ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B |
| USDC transmuter (pool) | terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj |
A Neutron route has the same shape. For example NTRN to USDC through ASTRO uses two astro_swap hops, untrn to factory/neutron1ffus553eet978k024lmssw0czsxwr97mggyv85lpcsdkft8v9ufsz3sa07/astro and then ASTRO to ibc/B559A80D62249C8AA07A380E2A2BEA6E5CA9A6F079C912C3A9E9B494105E4F81 (USDC), sent to the Neutron Router 2.0.
Simulating a Route
simulate_swap_operations takes the offer amount (in base units) and the same operations you will execute:
_36{_36 "simulate_swap_operations": {_36 "offer_amount": "10000000",_36 "operations": [_36 {_36 "astro_swap": {_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "uluna"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_36 }_36 }_36 }_36 },_36 {_36 "pool_swap": {_36 "pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"_36 }_36 }_36 }_36 }_36 ]_36 }_36}
The response is the amount of the last ask asset you would receive, in base units:
_3{_3 "amount": "394395"_3}
reverse_simulate_swap_operations answers the opposite question: it takes ask_amount and the operations and returns the offer amount needed, as a plain string (for example "25377928").
Setting minimum_receive
minimum_receive is the least amount of the final ask asset, in base units, that the recipient must receive. After the last hop the router compares the recipient's balance before and after the route and reverts the whole transaction if the difference is smaller.
Take your expected output and subtract the slippage you accept. With the simulation above and 1% slippage:
_2expected = 394395 (0.394395 USDC.inj)_2minimum_receive = 394395 * 99 / 100 = 390451 (rounded down)
Router 2.0 disables the pools' own spread checks, so a route with "minimum_receive": "1" is accepted but protects almost nothing. Set it from a price you trust. A simulation taken just before the swap protects you against the price moving between query and execution; a quote you computed independently also protects you against a pool whose price was already moved.
Native Routing
When the first offer asset is a native token, call execute_swap_operations on the router and attach the offer amount as funds.
_36{_36 "execute_swap_operations": {_36 "operations": [_36 {_36 "astro_swap": {_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "uluna"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_36 }_36 }_36 }_36 },_36 {_36 "pool_swap": {_36 "pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"_36 }_36 }_36 }_36 }_36 ],_36 "minimum_receive": "390451"_36 }_36}
| Parameter | Type | Description |
|---|---|---|
operations | Vec<SwapOperation> | The hops, in order (1 to 50) |
minimum_receive | Uint128 | Required, greater than zero. Least amount of the final ask asset the recipient must receive |
to | Option<String> | Recipient of the final ask asset, if not the sender |
A complete CosmJS script (see Swapping for the client setup):
_33const router = "terra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesf"; // Router 2.0.0_33const usdc = "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB";_33const usdcInj = "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B";_33const transmuter = "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj";_33_33const native = (denom) => ({ native_token: { denom } });_33_33const operations = [_33 { astro_swap: { offer_asset_info: native("uluna"), ask_asset_info: native(usdc) } },_33 { pool_swap: { pool_addr: transmuter, offer_asset_info: native(usdc), ask_asset_info: native(usdcInj) } },_33];_33_33const offerAmount = "10000000"; // 10 LUNA_33_33// 1. Simulate_33const { amount } = await client.queryContractSmart(router, {_33 simulate_swap_operations: { offer_amount: offerAmount, operations },_33});_33_33// 2. Accept at most 1% less than the simulation (integer math, rounded down)_33const minimumReceive = ((BigInt(amount) * 99n) / 100n).toString();_33_33// 3. Execute, attaching the offer asset_33const result = await signingClient.execute(_33 sender,_33 router,_33 { execute_swap_operations: { operations, minimum_receive: minimumReceive } },_33 "auto",_33 "",_33 [{ denom: "uluna", amount: offerAmount }]_33);_33_33console.log(result.transactionHash);
CW20 Routing
When the first offer asset is a CW20 token, call send on the token contract with the router as contract and the base64-encoded execute_swap_operations message as msg. The amount comes from the send; the hook takes operations, minimum_receive and an optional to.
The decoded hook message:
_35{_35 "execute_swap_operations": {_35 "operations": [_35 {_35 "astro_swap": {_35 "offer_asset_info": {_35 "token": {_35 "contract_addr": "terra1...token"_35 }_35 },_35 "ask_asset_info": {_35 "native_token": {_35 "denom": "uluna"_35 }_35 }_35 }_35 },_35 {_35 "astro_swap": {_35 "offer_asset_info": {_35 "native_token": {_35 "denom": "uluna"_35 }_35 },_35 "ask_asset_info": {_35 "native_token": {_35 "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"_35 }_35 }_35 }_35 }_35 ],_35 "minimum_receive": "123456"_35 }_35}
With CosmJS:
_21import { toBinary } from "@cosmjs/cosmwasm-stargate";_21_21const cw20Token = "terra1...token";_21_21const result = await signingClient.execute(_21 sender,_21 cw20Token, // the message goes to the token contract_21 {_21 send: {_21 contract: router,_21 amount: "1000000",_21 msg: toBinary({_21 execute_swap_operations: {_21 operations: cw20Operations, // the hops above_21 minimum_receive: minimumReceive, // from simulate_swap_operations, minus slippage_21 },_21 }),_21 },_21 },_21 "auto"_21);
Simulate CW20 routes the same way as native ones: pass the CW20 token asset info in the first operation.
Response Data
When a route starts with a native asset, the transaction's response data holds the total amount received, as SwapResponseData:
_3{_3 "return_amount": "394395"_3}
It is not set for routes that start with a CW20 send, because the CW20 contract replaces the response data.
Links
- Router contract
- Router 2.0 README and message types
- Swapping: single-pool swaps with
belief_priceandmax_spread - Contract Addresses