Skip to main content

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.

ChainRouter 2.0.0 (recommended)Router 1.3.1
Terraterra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesfterra18plp90j0zd596zt3zdsf0w9vvk5ukwlwzwkksxv9mdu8rscat9sqndk5qz
Neutronneutron1xuh7nqt486gkvkxdwt773fzs5uptxy0ylzehm3spq7rx8r2kaspqzu0hv6neutron1rwj6mfxzzrwskur73v326xwuff52vygqk73lr7azkehnfzz5f5wskwekf4

What changed in Router 2.0:

  • pool_swap hops. Besides astro_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_receive is 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 no max_spread parameter.
  • 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
}

Only route through pools you trust

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:

  1. LUNA to USDC (Noble) in the LUNA/USDC pool, found by the factory (astro_swap).
  2. USDC (Noble) to USDC.inj in the USDC transmuter, given by address (pool_swap).
AssetDenom on Terra
LUNAuluna
USDC (Noble)ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB
USDC.injibc/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:


_2
expected = 394395 (0.394395 USDC.inj)
_2
minimum_receive = 394395 * 99 / 100 = 390451 (rounded down)

minimum_receive is your only protection

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
}

ParameterTypeDescription
operationsVec<SwapOperation>The hops, in order (1 to 50)
minimum_receiveUint128Required, greater than zero. Least amount of the final ask asset the recipient must receive
toOption<String>Recipient of the final ask asset, if not the sender

A complete CosmJS script (see Swapping for the client setup):


_33
const router = "terra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesf"; // Router 2.0.0
_33
const usdc = "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB";
_33
const usdcInj = "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B";
_33
const transmuter = "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj";
_33
_33
const native = (denom) => ({ native_token: { denom } });
_33
_33
const 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
_33
const offerAmount = "10000000"; // 10 LUNA
_33
_33
// 1. Simulate
_33
const { 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)
_33
const minimumReceive = ((BigInt(amount) * 99n) / 100n).toString();
_33
_33
// 3. Execute, attaching the offer asset
_33
const 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
_33
console.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:


_21
import { toBinary } from "@cosmjs/cosmwasm-stargate";
_21
_21
const cw20Token = "terra1...token";
_21
_21
const 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.