@cetusprotocol/aggregator-sdk

Cetus Plus Swap Aggregator

Integrating Cetus-Aggregator-SDK: A Comprehensive Guide, Please see details in document.
Explore the document »

Welcome to Cetus Plus Swap Aggregator

Cetus plus swap aggregator is a high-speed and easy-to-integrate solution designed to optimize your trading experience on the Sui blockchain. This aggregator integrates multiple mainstream decentralized exchanges (DEX) on the Sui chain, including various types of trading platforms, providing users with the best trading prices and the lowest slippage.

Core Advantages:

High-Speed Transactions: Thanks to advanced algorithms and efficient architecture, our aggregator can execute transactions at lightning speed, ensuring users get the best opportunities in a rapidly changing market.

Easy Integration: The aggregator is designed to be simple and easy to integrate. Whether you are an individual developer or a large project team, you can quickly connect and deploy.

Multi-Platform Support: Currently, we have integrated multiple mainstream DEXs on the Sui chain, including cetus, deepbook, kriya, flowx, aftermath, afsui, haedal, volo, turbos etc, allowing users to enjoy a diversified trading experience on a single platform.

By using our aggregator, you can trade more efficiently and securely on the Sui blockchain, fully leveraging the various opportunities brought by decentralized finance (DeFi).

Supported Providers

The Cetus Aggregator SDK supports 25+ decentralized exchanges (DEXs) on the Sui blockchain:

• Cetus
• DeepBook V3
• Kriya V2/V3
• FlowX V2/V3
• Turbos
• Aftermath
• Haedal
• Volo
• AfSui
• Bluemove
• Scallop
• Suilend
• Bluefin
• HaedalHMM
• Alphafi
• SpringSui
• Steamm CPMM
• Steamm OMM
• Metastable
• Obric
• HaWAL
• Momentum
• Magma
• Sevenk

Aggregator SDK V3

Advantages of Aggregator Client V3

The new Aggregator Client V3 offers significant improvements over the previous version:

Transaction Traceability

• Complete Transaction History: All swap transactions are fully traceable on the blockchain
• Detailed Route Information: Track exactly which DEXs and pools were used in multi-hop swaps
• Gas Optimization Transparency: See how transactions were optimized to reduce gas costs

Transaction Merging for Gas Optimization

• Reduced Gas Costs: Significantly lower transaction fees through optimized execution paths
• Smart Route Aggregation: Automatically combines similar operations to minimize gas usage

Enhanced Features

• Increased Reliability: More robust transaction execution with better error handling

Migration from Aggregator Client to V3

Installation

Both versions use the same package:

npm install @cetusprotocol/aggregator-sdk

Key Changes

• Client Initialization

  // V2 (Legacy)
  const client = new AggregatorClient({})
  
  // V3 (New)
  const client = new AggregatorClient({})
  

• Router Finding

  // Both versions use the same API
  const routers = await client.findRouters({
    from: "0x2::sui::SUI",
    target:
      "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
    amount: new BN(1000000),
    byAmountIn: true,
  })
  

• Transaction Building

  // V2 Method
  await client.buildRouterSwap({
    routers,
    txb,
    inputCoin,
    slippage: 0.01,
  })
  
  // V3 Method (Recommended)
  await client.fastRouterSwap({
    routers,
    txb,
    slippage: 0.01,
  })
  
  // V3 Alternative (For PTB building)
  const targetCoin = await client.routerSwap({
    routers,
    txb,
    inputCoin,
    slippage: 0.01,
  })
  

• Benefits of Migration

  • Reduced gas costs through transaction merging
  • Better transaction traceability
  • Improved error handling and reliability
  • Access to latest DEX integrations

Install

The SDK is published to npm registry. To use the SDK in your project, you can

npm install @cetusprotocol/aggregator-sdk

Usage

1. Init client with rpc and package config

const client = new AggregatorClient({})

2. Get best router swap result from aggregator service

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
})

3. Confirm and do fast swap

const txb = new Transaction()

if (routerRes != null) {
  await client.fastRouterSwap({
    routers,
    txb,
    slippage: 0.01,
  })

  const result = await client.devInspectTransactionBlock(txb, keypair)

  if (result.effects.status.status === "success") {
    console.log("Sim exec transaction success")
    const result = await client.signAndExecuteTransaction(txb, keypair)
  }
  console.log("result", result)
}

4. Build PTB and return target coin

const txb = new Transaction()
const byAmountIn = true

if (routerRes != null) {
  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, targetCoinType)

  const result = await client.devInspectTransactionBlock(txb, keypair)

  if (result.effects.status.status === "success") {
    console.log("Sim exec transaction success")
    const result = await client.signAndExecuteTransaction(txb, keypair)
  }
  console.log("result", result)
}

Aggregator Contract Interface

Tags corresponding to different networks

Contract	Tag of Repo	Latest published at address
CetusAggregatorV2	mainnet	0x3864c7c59a4889fec05d1aae4bc9dba5a0e0940594b424fbed44cb3f6ac4c032
CetusAggregatorV2ExtendV1	mainnet	0x39402d188b7231036e52266ebafad14413b4bf3daea4ac17115989444e6cd516
CetusAggregatorV2ExtendV2	mainnet	0x368d13376443a8051b22b42a9125f6a3bc836422bb2d9c4a53984b8d6624c326

Example

CetusAggregatorV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/mainnet", rev = "mainnet", override = true }

CetusAggregatorV2ExtendV1 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v1", rev = "mainnet", override = true }

CetusAggregatorV2ExtendV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v2", rev = "mainnet", override = true }

Simple Aggregator Contract Interface

• include: cetus, flowxv3, turbos, bluefin, haedalhmm, momentum, obric

Tags corresponding to different networks

Contract	Tag of Repo	Latest published at address
CetusAggregatorSimple	mainnet	0x44ca6438ab034be95cedfca7d4070e6d33fa12e088e9dce13abb1bf055093264

Example

CetusAggregatorSimple = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/simple-mainnet", rev = "mainnet-v1.50.2", override = true }

Usage

Cetus clmm interface is not complete(just have function definition), so it will fails when sui client check the code version. However, this does not affect its actual functionality. Therefore, we need to add a --dependencies-are-root during the build.

sui move build --dependencies-are-root && sui client publish --dependencies-are-root

More About Cetus

Use the following links to learn more about Cetus:

Learn more about working with Cetus in the Cetus Documentation.

Join the Cetus community on Cetus Discord.