Features Available

1. Find router

Func client.findRouters

Params

Required parameters

Name	Type	Details
from	String	The coin type of input coin.
target	String	The coin type of output coin.
amount	BN	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

Actually,we recommend not setting these optional parameters, as our aggregator service will automatically optimize these settings based on the SDK version. This ensures optimal transactions and accuracy

Name	Type	Details
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.

Example

import { AggregatorClient } 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 routers = await client.findRouters({
  from,
  target,
  amount,
  byAmountIn: true, // `true` means fix input amount, `false` means fix output amount
})

2. Build fast swap transaction

This method will send swaped coins to user directly. Here are two type fast swap params:

• BuildFastRouterSwapParams: The old parameter types will continue to be supported.

• BuildFastRouterSwapParamsV2: The new parameter types is more clear and can support dynamic update latest package by aggregator.

We recommend using the V2 version of the parameters if you upgrade to the latest SDK version (vcersion > v0.3.18). 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 structure returned by find router.

BuildFastRouterSwapParamsV2

Required Params

Name	Type	Details
routers	RouterData Object	returned by find router 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

Name	Type	Details
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 routers = 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({
  routers,
  txb,
  slippage: 0.01,
})

3. Build swap transaction and return target coin object

This method will build transaction and return coin objects, used to build ptb.

• BuildFastRouterSwapParams: The old parameter types will continue to be supported.

• BuildFastRouterSwapParamsV2: The new parameter types is more clear and can support dynamic update latest package by aggregator.

BuildRouterSwapParamsV2

Required Params

Name	Type	Details
routers	RouterData Object	Returned by find router method
inputCoin	TransactionObjectArgument	This represents the input coin object. If you only support swaps with a fixed input, simply extract a fixed amount from the coin object. If you support fixed output, you need to extract an amount limited by the specified constraints from the coin object.
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

Name	Type	Details
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 routers = 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({
  routers,
  txb,
  inputCoin,
  slippage: 0.01,
})

// you can use this target coin object argument to build your ptb.
client.transferOrDestoryCoin(
    txb,
    targetCoin,
    target
)

Why use v2 swap params?

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.

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.

Common Errors

1. 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 routers = 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"]
})