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:

$3

- 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

$3

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

$3

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

Migration from V2 to V3 API

$3

Both V2 and V3 APIs use the same package:

``bash
npm install @cetusprotocol/aggregator-sdk
`

$3

Important: Both V2 and V3 use the same AggregatorClient class. The main differences are:
- Return types: V3 uses RouterDataV3 (with flattened paths) instead of V2's RouterData (with nested routes)
- Swap methods: V3 introduces fastRouterSwap() for automatic coin handling
- Transaction structure: V3 optimizes gas through transaction merging

1. Client Initialization (Same for both)

`typescript
import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"

const client = new AggregatorClient({
// Optional: Add custom configuration
})
`

2. Router Finding (API unchanged, but return type differs)

`typescript
import BN from "bn.js"

// Works with both V2 and V3
const routers = await client.findRouters({
from: "0x2::sui::SUI",
target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
amount: new BN(1000000),
byAmountIn: true,
})

// V2 returns: RouterData with routes[]
// V3 returns: RouterDataV3 with paths[]
`

3. Transaction Building

`typescript
import { Transaction } from "@mysten/sui/transactions"

const txb = new Transaction()

// V3 Method (Recommended) - Automatic coin handling
await client.fastRouterSwap({
router: routers,
txb,
slippage: 0.01,
})

// V3 Alternative - Manual coin handling for PTB building
const targetCoin = await client.routerSwap({
router: routers,
txb,
inputCoin, // TransactionObjectArgument
slippage: 0.01,
})
`

4. Benefits of V3 Migration
- Reduced gas costs through transaction merging
- Better transaction traceability on-chain
- Improved error handling and reliability
- Access to latest DEX integrations
- Automatic coin management with fastRouterSwap()

Install

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

`
npm install @cetusprotocol/aggregator-sdk
`

Usage

$3

`typescript
import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
import { Transaction } from "@mysten/sui/transactions"
import BN from "bn.js"
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519"

// Initialize your keypair (example using Ed25519)
const keypair = Ed25519Keypair.deriveKeypair("your-mnemonic-phrase")
`

$3

`typescript
import { Env } from "@cetusprotocol/aggregator-sdk"
import { getFullnodeUrl, SuiClient } from "@mysten/sui/client"

const client = new AggregatorClient({
// Optional configuration parameters:

// Network environment (default: Mainnet)
env: Env.Mainnet, // or Env.Testnet

// Custom API endpoint for aggregator service
// endpoint: "https://api-sui.cetus.zone",

// Custom Sui client (default: mainnet RPC)
// client: new SuiClient({ url: getFullnodeUrl("mainnet") }),

// Partner ID for revenue sharing
// partner: "your-partner-id",

// CETUS DLMM specific partner ID
// cetusDlmmPartner: "your-dlmm-partner-id",

// Overlay fee rate (0 to 0.01 for 0-1%)
// overlayFeeRate: 0.001, // 0.1%

// Overlay fee receiver address
// overlayFeeReceiver: "0x...",

// Custom Pyth oracle URLs
// pythUrls: ["https://hermes.pyth.network"],

// API key for rate limiting
// apiKey: "your-api-key",
})
`

$3

Get the optimal swap route from the aggregator service:

`typescript
const amount = new BN(1000000) // 1 SUI (with 6 decimals)
const from = "0x2::sui::SUI"
const target = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"

const routers = await client.findRouters({
from,
target,
amount,
byAmountIn: true, // true = fixed input amount, false = fixed output amount
// Optional parameters:
// depth: 3, // Maximum number of hops
// providers: ["CETUS", "TURBOS"], // Limit to specific DEXs
})

// Check if a valid route was found
if (!routers || routers.insufficientLiquidity) {
console.error("No valid route found or insufficient liquidity")
process.exit(1)
}

console.log(Expected output: ${routers.amountOut.toString()})
`

$3

The easiest way to execute a swap with automatic coin management:

`typescript
const txb = new Transaction()

await client.fastRouterSwap({
router: routers,
txb,
slippage: 0.01, // 1% slippage tolerance
// Optional:
// partner: "your-partner-id",
// payDeepFeeAmount: 1000000, // For DeepBook V3 pools
})

// Simulate the transaction first
const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)

if (dryRunResult.effects.status.status === "success") {
console.log("Simulation successful, executing transaction...")

// Execute the actual transaction
const result = await client.signAndExecuteTransaction(txb, keypair)
console.log("Transaction result:", result)
} else {
console.error("Simulation failed:", dryRunResult.effects.status)
}
`

$3

Use this when you need to build complex programmable transaction blocks:

`typescript
import { coinWithBalance } from "@mysten/sui/transactions"

const txb = new Transaction()

// Create input coin object
// Option 1: From existing coin object
const inputCoin = txb.object("0x...") // Your coin object ID

// Option 2: Create coin with specific balance
// const inputCoin = coinWithBalance({
// type: from,
// balance: amount.toString()
// })

// Execute swap and get output coin
const targetCoin = await client.routerSwap({
router: routers,
txb,
inputCoin,
slippage: 0.01, // 1% slippage tolerance
// Optional:
// partner: "your-partner-id",
// deepbookv3DeepFee: deepCoinObject, // For DeepBook V3
})

// Use the target coin in your custom PTB logic
// For example, transfer to recipient or use in another DeFi protocol
txb.transferObjects([targetCoin], keypair.toSuiAddress())

// Or destroy if sending to current address
// client.transferOrDestroyCoin(txb, targetCoin, target)

// Simulate and execute
const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)

if (dryRunResult.effects.status.status === "success") {
console.log("Simulation successful, executing transaction...")
const result = await client.signAndExecuteTransaction(txb, keypair)
console.log("Transaction result:", result)
} else {
console.error("Simulation failed:", dryRunResult.effects.status)
}
`

$3

Protect against excessive input amounts:

`typescript
const txb = new Transaction()
const inputCoin = txb.object("0x...") // Your coin object

const targetCoin = await client.routerSwapWithMaxAmountIn({
router: routers,
txb,
inputCoin,
slippage: 0.01,
maxAmountIn: new BN(2000000), // Maximum 2 SUI allowed
})

// Transaction will abort if input amount exceeds maxAmountIn
`

$3

`typescript
try {
const routers = await client.findRouters({
from,
target,
amount,
byAmountIn: true,
})

if (!routers) {
throw new Error("No route found")
}

if (routers.insufficientLiquidity) {
throw new Error("Insufficient liquidity for this swap")
}

if (routers.error) {
throw new Error(Router error: ${routers.error.msg})
}

// Proceed with swap...
} catch (error) {
console.error("Swap failed:", error)
}
`

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.