Features Available
1. Find router
Func client.findRouters()
Aggregator Client v2 (v0.x.x) vs v3 (v1.x.x) Compatibility:
Input: The
findRouterInput
parameter structure is identical for both versionsOutput Changes: v3 replaces the
router
field withpaths
Optimization: v3 consolidates duplicate pools in the response, resulting in significant gas savings for multi-path routes
Params
Required parameters
from
String
The coin type of input coin.
target
String
The coin type of output coin.
amount
BN | string | number| bigint
The amount of input or output,determined byAmountIn
byAmountIn
Boolean
true
means fixed the amount of input, false
means fixed the amount of output.
Optional parameters
In principle, we do not recommend adding these optimal parameters if you don't have any specific custon needs, because our aggregator service will automatically optimize these settings in each SDK update to pursue optimal pricing and performance of transactions.
providers
String Array
Now, support cetus, deepbook v2/v3, kriya v2/v3, flowx v2/v3, aftermath, turbos, afsui, volo, haedal, bluemove, scallop, suilend, bluefin. If not set, it's will default support best providers by sdk version.
depth
Number
now depths support betweent 1 and 3, default setting is 3, it means you can get 3 hops path.
splitAlgorithm
String
devide_equally or geometric, recommand just use default devide_equally.
splitFactor
Number
used to contral geometric split width.
splitCount
Number
this field represents the maximum number of splits for a transaction. If you do not want to split, set it to 1. The default value is 20.
ResponseV3
When using Aggregator SDK v3 (version 1.0.0 or higher), the findRouter
method will return data in the RouterV3 structure.
quoteID
string
A randomly generated ID from the aggregator service for tracking index transactions and quotes.
amountIn
BN
Total amount in.
amountOut
BN
Total amount out.
byAmountIn
Boolean
true
means fixed the amount of input, false
means fixed the amount of output. This is the same as request parameters.
paths
Path[]
All liquidity paths data.
insufficientLiquidity
Boolean
true
means liquidity insufficient, false
means liquidity enough.
deviationRatio
Number
Price deviation ratio, (0.01 means 1%), indicating the degree of difference between the aggregator result and market price. When the price deviation ratio is undefined (no reference market price available) or relatively large (significant deviation from existing market prices), provide users with a reference option on whether to execute the trade at the current price to avoid potential asset losses.
packages
Map<string, string>
When user pass new version parameters, it will return newest aggregator packages data.
overlayFee
Number
The amount for overlay fee.
totalDeepFee
Number
Calculated need deep fee for deep pools.
error
RouterError
Error code and msg for aggregator.
ResponseV2
quoteID
string
A randomly generated ID from the aggregator service for tracking index transactions and quotes.
amountIn
BN
Total amount in.
amountOut
BN
Total amount out.
byAmountIn
Boolean
true
means fixed the amount of input, false
means fixed the amount of output. This is the same as request parameters.
routes
Router[]
All liquidity routes data.
insufficientLiquidity
Boolean
true
means liquidity insufficient, false
means liquidity enough.
deviationRatio
Number
Price deviation ratio, (0.01 means 1%), indicating the degree of difference between the aggregator result and market price. When the price deviation ratio is undefined (no reference market price available) or relatively large (significant deviation from existing market prices), provide users with a reference option on whether to execute the trade at the current price to avoid potential asset losses.
packages
Map<string, string>
When user pass new version parameters, it will return newest aggregator packages data.
overlayFee
Number
The amount for overlay fee.
totalDeepFee
Number
Calculated need deep fee for deep pools.
error
RouterError
Error code and msg for aggregator.
Example
import { AggregatorClient, getAllProviders } from "@cetusprotocol/aggregator-sdk"
import BN from "bn.js"
const client = new AggregatorClient({})
const amount = new BN(1000000)
const from = "0x2::sui::SUI"
const target = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
const providers = getAllProviders()
const router = await client.findRouters({
from,
target,
amount,
byAmountIn: true, // `true` means fix input amount, `false` means fix output amount
providers
})
2. Build fast swap transaction
This method will send swaped coins to user directly. Here are three type fast swap params:
BuildFastRouterSwapParamsV3
: The new SDK version only supports this parameter format. (Only support in aggregator v3 version, version ≥ v1.0.0)BuildFastRouterSwapParamsV2
: This legacy parameter is no longer supported in the latest SDK versions (v >= 1.0.0).. (Only support in aggregator v2 version, v1.0.0> version >= v0.0.0)BuildFastRouterSwapParams
: Here's the English translation: This legacy parameter is no longer supported in the latest SDK versions (v >= 1.0.0).(Only support in aggregator v2 version, v1.0.0> version >= v0.0.0)
We recommend using the V3 version of the parameters if you upgrade to the latest SDK versions (version > v1.1.1). This way, if a contract on any platform undergoes a breaking update in the future, you won't need to make any changes; the SDK will automatically update to the latest contract address through the response returned by find router methods, while also reducing gas costs by leveraging the most optimized contract versions
BuildFastRouterSwapParamsV3
Required Params
router
RouterDataV3 Object
returned by find router method in latest aggregator sdk version
slippage
Number
A value between 0 and 1, representing the maximum allowed price slippage as a percentage. A value of 0.01 allows up to 1% price slippage. This parameter is crucial for protecting your assets in a rapidly changing market.
txb
Transaction
The programmable transaction builder.
Optional parameters
partner
String
The partner address. Details about partner can be found here. You can now set the partner directly during client initialization. This parameter will soon be deprecated; please migrate your configuration.
refreshAllCoins
Boolean
If true, retrieves all coin types when setting up the swap; if false, uses the existing coins.
payDeepFeeAmount
Number
The deep amount for pay deep fee in deepbookv3 path. Currently, all pools that charge a swap fee are covered by Cetus.
Example
import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
import { Transaction } from '@mysten/sui/transactions';
const client = new AggregatorClient({})
const amount = new BN(1000000)
const from = "0x2::sui::SUI"
const target = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
const router = await client.findRouters({
from,
target,
amount,
byAmountIn: true, // `true` means fix input amount, `false` means fix output amount
})
const txb = new Transaction()
await client.fastRouterSwap({
router,
txb,
slippage: 0.01,
})
3. Build swap transaction and return target coin object(use the whole input coin)
This method will completely consume the input coin amount and return coin objects, used to build ptb.
BuildRouterSwapParamsV3
: The new parameter types is more clear and can support dynamic update latest package by aggregator.BuildRouterSwapParamsV2
: The new parameter types is more clear and can support dynamic update latest package by aggregator.BuildRouterSwapParams
: The old parameter types will continue to be supported.
BuildRouterSwapParamsV3
Required Params
routers
RouterData Object
Returned by find router method
inputCoin
TransactionObjectArgument
The input coin object to be swapped. Important: This method will completely consume the input coin amount. If you need to set a maximum limit on how much of the input coin can be used (for example, to implement slippage protection on the input side), you should use routerSwapWithMaxAmountIn
method.
slippage
Number
A value between 0 and 1, representing the maximum allowed price slippage as a percentage. A value of 0.01 allows up to 1% price slippage. This parameter is crucial for protecting your assets in a rapidly changing market.
txb
Transaction
The programmable transaction builder.
Optional parameters
partner
String
The partner address. Details about partner can be found here. You can now set the partner directly during client initialization. This parameter will soon be deprecated; please migrate your configuration.
refreshAllCoins
Boolean
If true, retrieves all coin types when setting up the swap; if false, uses the existing coins.
deepbookv3DeepFee
TransactionObjectArgument
The deep fee obejct argument for pay deep fee in deepbookv3 path. Currently, all pools that charge a swap fee are covered by Cetus.
Example
import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
import { Transaction } from '@mysten/sui/transactions';
const client = new AggregatorClient({})
const amount = new BN(1000000)
const from = "0x2::sui::SUI"
const target = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
const router = await client.findRouters({
from,
target,
amount,
byAmountIn: true, // `true` means fix input amount, `false` means fix output amount
})
const txb = new Transaction()
const targetCoin = await client.routerSwap({
router,
txb,
inputCoin, // the whole coin will be used in the swap.
slippage: 0.01,
})
// you can use this target coin object argument to build your ptb.
client.transferOrDestoryCoin(
txb,
targetCoin,
target
)
4. Build swap transaction and return target coin object (with maximum input protection)
This method builds a swap transaction with maximum input amount validation. It returns the target coin object and can be used to build PTB (Programmable Transaction Blocks).
When to use routerSwapWithMaxAmountIn
routerSwapWithMaxAmountIn
Use this method when you need to:
Protect against excessive input usage - Ensure the swap doesn't consume more than expected
Implement input-side slippage protection - Set a hard cap on how much input can be used
Handle dynamic coin balances - When you're not certain of the exact coin balance being provided
Build complex PTB logic - Where you need precise control over maximum input consumption
Comparison: routerSwap
vs routerSwapWithMaxAmountIn
routerSwap
vs routerSwapWithMaxAmountIn
Feature
routerSwap
routerSwapWithMaxAmountIn
Input Coin Usage
Consumes ENTIRE inputCoin
May use LESS than inputCoin
Validation
No maximum limit
Validates against maxAmountIn
On-chain Behavior
Uses all provided coins
Aborts if amount exceeds limit
Use Case
Standard swaps with known amounts
Swaps with dynamic/uncertain balances
Return Value
Target coin object
Target coin object
⚠️ Critical Difference: inputCoin Behavior
routerSwap
- Full Consumption
// This method will consume the ENTIRE inputCoin provided
// The whole coin will be used in the swap - there is NO partial usage
const targetCoin = await client.routerSwap({
router: routers,
txb,
inputCoin, // ⚠️ This ENTIRE coin will be consumed
slippage: 0.01,
})
Important: If you provide a coin with 1000 SUI, the entire 1000 SUI will be used in the swap, regardless of the router's amountIn
. This method does not support partial coin usage.
routerSwapWithMaxAmountIn
- Protected Consumption
// This method validates the amount and can work with dynamic balances
const targetCoin = await client.routerSwapWithMaxAmountIn({
router: routers,
txb,
inputCoin, // ✅ Only the required amount will be used
slippage: 0.01,
maxAmountIn: new BN(2000000), // Hard limit: max 2 SUI
})
Important: This method adds on-chain validation to ensure the swap does not exceed maxAmountIn
. The transaction will abort if the required amount exceeds this limit, protecting your assets from unexpected large swaps.
BuildRouterSwapParamsV3 (with maxAmountIn)
Extension of BuildRouterSwapParamsV3
with additional maximum amount validation.
Required Params
router
RouterDataV3 Object
Returned by findRouters
method. Must include the packages
field with aggregator v3 package address.
inputCoin
TransactionObjectArgument
The input coin object to be swapped.Important: Unlike routerSwap
, this methods comes with a maxAmountIn input and the final executed amount won't exceed this cap
slippage
Number
A value between 0 and 1, representing the maximum allowed price slippage as a percentage. A value of 0.01 allows up to 1% price slippage. This parameter protects your assets from unfavorable price movements during swap execution.
txb
Transaction
The programmable transaction builder.
maxAmountIn
BN | string | number| bigint
Maximum input amount allowed for this swap. The transaction will abort on-chain if the swap requires more than this amount. This provides an additional layer of protection against unexpected large swaps or slippage on the input side.
Optional Parameters
partner
String
The partner address. Details about partner can be found here.You can now set the partner directly during client initialization. This parameter will soon be deprecated; please migrate your configuration.
deepbookv3DeepFee
TransactionObjectArgument
The DEEP token object for paying fees in DeepBook V3 pools. Currently, all pools that charge a swap fee are covered by Cetus, so you typically don't need to provide this.
fixable
Boolean
Advanced parameter for fixable router swap. Used in special swap scenarios. Default: false
Key Feature: This method validates that the input coin amount does not exceed the specified maxAmountIn
. The transaction will abort on-chain if the validation fails.
Code Examples
import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
import { Transaction } from "@mysten/sui/transactions"
import BN from "bn.js"
const client = new AggregatorClient({})
const txb = new Transaction()
// Find the best route
const routers = await client.findRouters({
from: "0x2::sui::SUI",
target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
amount: new BN(1000000), // 1 SUI
byAmountIn: true,
})
// Your input coin (could be from wallet or created in PTB)
const inputCoin = txb.object("0x...")
// Execute swap with maximum amount protection
const targetCoin = await client.routerSwapWithMaxAmountIn({
router: routers,
txb,
inputCoin,
slippage: 0.01, // 1% slippage
maxAmountIn: new BN(1500000), // Maximum 1.5 SUI allowed
})
// If the swap requires more than 1.5 SUI, the transaction will ABORT
// Use the target coin in your PTB
txb.transferObjects([targetCoin], yourAddress)
5. FAQ
5.1. Why use v3 swap params?
1. Automatically merges duplicate paths
By combining the latest path merging and sorting algorithms, duplicate pools are consolidated, resulting in significant gas savings when dealing with multiple split paths.
2. Support dynamic use latest package version
The new parameters will pass the entire result from find router, which includes the latest contract address. However, this feature is only effective in SDK versions greater than 0.3.18.
In the future, we will continue to support the old version of swap parameters in both swap methods. However, upgrading to the new version will allow you to avoid mandatory SDK version updates.
3. Remove duplicate parameter byAmountIn
Now, the find router result will return the value based on the amount in, allowing you to directly obtain it from the find router result in the new swap parameters.
5.2. How to Migrate to Aggregator V3?
No code changes needed for basic usage:
Use the latest sdk version. (version >= v1.1.1)
Client initialization stays the same
findRouter
now returns V3 structure automaticallyfastRouterSwap
androuterSwap
accept the new format transparentlyUpdate display logic only if showing detailed
RouterDataV3
to users
5.3. How to set providers?
You can ignore the providers parameters; the aggregator server will automatically set all usable providers based on the SDK version.
You can use the
getAllProviders()
method to retrieve all providers. Additionally, you can use thegetProvidersIncluding()
andgetProvidersExcluding()
methods to filter out specific providers or select only certain ones from the complete list.
import { getAllProviders, getProvidersExcluding } from "@cetusprotocol/aggregator-sdk"
const allProviders = getAllProviders()
console.log(allProviders)
[
'CETUS', 'KRIYA',
...
'MOMENTUM', 'STEAMM_OMM',
'STEAMM_OMM_V2'
]
const providersExcept = getProvidersExcluding(["CETUS"])
console.log(providersExcept)
[
'KRIYA', 'FLOWX',
...
'STEAMM_OMM', 'STEAMM_OMM_V2'
]
While you can manually specify the providers you want to use, as the number of providers increases, manual configuration may lead to the omission of some providers, which could affect your price advantage."
5.4. How to fix error "All Pyth price nodes are unavailable. Cannot fetch price data. Please switch to or add new available Pyth nodes. Detailed error: aborted"?
Reason: Some providers, such as Headalpmm and Metastable, rely on Pyth oracle prices when building transactions. Currently, we have a default configuration that connects to Pyth's publicly available node. However, if you frequently build transactions, you may encounter limitations with the Pyth public nodes(https://hermes.pyth.network).
Solutions: We recommend setting up a private Pyth node interface as an additional backup. This will ensure uninterrupted access to HaedalHMM and Metastable, even if the public node experiences occasional downtime.
const client = new AggregatorClient({
// endpoint, // If you do not have a exclusive aggregator api domain,just use cetus default aggregator endpoints.
signer: wallet,
client: suiClient,
env: Env.Mainnet,
pythUrls: ["YOUR_PYTH_URL", "ANOTHER_PYTH_URL"],
})
Another way, you can opt not to use Headalpmm and Metastable, but this will require you to manually configure the provider when find router.
const router = await client.findRouters({
from,
target,
amount,
byAmountIn: true,
providers: ["CETUS","SCALLOP","AFTERMATH","FLOWXV3","AFSUI","STEAMM","VOLO","KRIYAV3","KRIYA","ALPHAFI","FLOWX","BLUEMOVE","DEEPBOOKV3","BLUEFIN","HAEDAL","TURBOS","SPRINGSUI","STEAMM","METASTABLE","HAWAL","OBRIC"]
})
Last updated