Cetus Aggregator SDK Skill

A Claude Code skill for working with the Cetus Aggregator SDK to execute optimized swaps across multiple Sui DEXs. This skill provides comprehensive tools for multi-DEX routing, price discovery, and gas-optimized swap execution using the @cetusprotocol/aggregator-sdk library.

Instructions

Use this skill when you need to execute token swaps on the Sui blockchain. Includes:

1. SDK Initialization: Configure environment, wallet, and RPC connection
2. Multi-DEX Routing: Find optimal price routes across 30+ DEXs
3. Swap Execution: Execute fast swaps or manual route swaps
4. Slippage Protection: Configure slippage tolerance to protect transactions
5. Gas Optimization: Dynamic gas management and budget settings
6. Protocol Fees: Configure overlay fees and recipient addresses
7. Error Handling: Comprehensive error handling and market condition validation

Quick Start

// Initialize SDK
import { AggregatorClient, Env } from '@cetusprotocol/aggregator-sdk'
import { SuiClient } from '@mysten/sui/client'
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'

const mnemonics: string = process.env.MNEMONICS!;
const i = 0;
const path = `m/44'/784'/${i}'/0'/0'`;
const keypair = Ed25519Keypair.deriveKeypair(mnemonics, path);
const wallet = keypair.toSuiAddress();

const suiClient = new SuiClient({
    url: process.env.RPC!,
});

const client = new AggregatorClient({
    signer: wallet,
    client: suiClient,
    env: Env.Mainnet,
});

Core Features

SDK Initialization

• Environment Configuration: Mainnet/Testnet support
• Wallet Management: Derive keypairs from mnemonics
• RPC Configuration: Custom RPC endpoint support

Multi-DEX Routing

• 30+ DEX Support: Access major Sui DEXs
• Optimal Price Discovery: Best price routing across providers
• Provider Selection: Customizable DEX provider list

Swap Execution

• Fast Router Swap: Automatic token management
• Manual Router Swap: Advanced token control
• Slippage Protection: Configurable slippage tolerance

Advanced Features

• Overlay Fees: Protocol fee integration
• Pyth Oracle: Price oracle integration
• Gas Optimization: Dynamic gas management

Usage Examples

Basic Swap Operations

// Find optimal routes
const routers = await client.findRouters({
  from: "0x2::sui::SUI",
  target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
  amount: new BN(1000000000),
  byAmountIn: true,
  providers: ["CETUS", "KRIYA", "AFTERMATH"]
});

// Execute fast swap
const txb = new Transaction();
await client.fastRouterSwap({
  router: routers,
  txb,
  slippage: 0.01,
  refreshAllCoins: true,
});

const result = await client.signAndExecuteTransaction(txb, keypair);
console.log("Swap executed:", result);

Query Swap Function

import { Transaction, coinWithBalance } from '@mysten/sui/transactions'
import BN from 'bn.js'
import { bcs } from '@mysten/sui/bcs'

export const querySwap = async (client: AggregatorClient, keypair: Ed25519Keypair, from: string, target: string, amount: string, amountOut: string) => {
    let router: any = null;
    let txb: any = null;
    let targetCoin: any = null;

    try {
        const wallet = keypair.toSuiAddress();

        const amountIn = new BN(amount);
        router = await client.findRouters({
            from,
            target,
            amount: amountIn,
            byAmountIn: true,
            providers: ["CETUS","SCALLOP","AFTERMATH","FLOWXV3","AFSUI","STEAMM","VOLO","KRIYAV3","KRIYA","ALPHAFI","FLOWX","BLUEMOVE","DEEPBOOKV3","BLUEFIN","HAEDAL","TURBOS","SPRINGSUI","STEAMM","METASTABLE","HAWAL","OBRIC"]
        });

        if (router === null) {
            return;
        }

        const amountOutput = router.amountOut;

        if (amountOutput.lt(new BN(amountOut))) {
            console.log("Trade condition not met");
            return;
        }

        txb = new Transaction();

        targetCoin = await client.routerSwap({
            router,
            txb,
            inputCoin: coinWithBalance({ type: from, balance: BigInt(amount) }),
            slippage: 0.01,
        });

        txb.moveCall({
            package: "0xe450c157978058fc23078941924ad91bfe3022db6243ffa432f7209ad5bc9889",
            module: "utils",
            function: "check_coin_threshold",
            arguments: [
                targetCoin,
                txb.pure(bcs.U64.serialize(BigInt(amountOut))),
            ],
            typeArguments: [
                target,
            ],
        });
        txb.transferObjects([targetCoin], wallet);

        txb.setSender(wallet);
        txb.setGasBudget(1_000000000);

        const result = await client.client.signAndExecuteTransaction({ transaction: txb, signer: keypair });
        console.log("result", result);

    } catch (error) {
        console.log("querySwap error:", error);
    } finally {
        router = null;
        txb = null;
        targetCoin = null;

        if (global.gc) {
            global.gc();
        }
    }
}

Provider Management

import { getAllProviders, getProvidersExcluding, getProvidersIncluding } from '@cetusprotocol/aggregator-sdk'

// Get all supported providers
const allProviders = getAllProviders()

// Get providers excluding specific ones
const filteredProviders = getProvidersExcluding(["CETUS", "KRIYA"])

// Get only specific providers
const specificProviders = getProvidersIncluding(["TURBOS", "AFTERMATH"])

Supported DEXs

The aggregator supports 30+ DEXs, including:

• CETUS, KRIYA (V2/V3), FLOWX (V2/V3), TURBOS, AFTERMATH
• HAEDAL, VOLO, AFSUI, BLUEMOVE, DEEPBOOKV3
• SCALLOP, SUILEND, BLUEFIN, HAEDALPMM, ALPHAFI
• SPRINGSUI, STEAMM, METASTABLE, OBRIC, HAWAL
• MOMENTUM, STEAMM_OMM, STEAMM_OMM_V2, MAGMA, SEVENK
• HAEDALHMMV2, FULLSAIL

Common Token Types

// Mainnet token types
const SUI = "0x2::sui::SUI"
const USDC = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
const USDT = "0x375f70cf2ae4c00bf37117d0c85a2c71545e6ee05c4a5c7d282cd66a4504b068::usdt::USDT"
const CETUS = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
const AFSUI = "0xf325ce1300e8dac124071d3152c5c5ee6174914f8bc2161e88329cf579246efc::afsui::AFSUI"
const HA_SUI = "0xbde4ba4c2e274a60ce15c1cfff9e5c42e41654ac8b6d906a57efa4bd3c29f47d::hasui::HA_SUI"

Best Practices

Route Validation

// Always check for null routes
const routers = await client.findRouters({
  from: "0x2::sui::SUI",
  target: "0x...::cetus::CETUS",
  amount: new BN(1000000000),
  byAmountIn: true,
});

if (routers) {
  // Execute swap
} else {
  console.log("No routes found");
}

Slippage Management

// Use appropriate slippage based on market conditions
const slippage = 0.01; // 1% for stable pairs
const slippage = 0.05; // 5% for volatile pairs

Gas Optimization

// Set appropriate gas budget
txb.setGasBudget(1_000000000); // 1 SUI for complex swaps
txb.setGasBudget(500000000);   // 0.5 SUI for simple swaps

Error Handling

try {
  const routers = await client.findRouters({
    from: "0x2::sui::SUI",
    target: "0x...::cetus::CETUS",
    amount: new BN(1000000000),
    byAmountIn: true,
  });

  if (routers) {
    const txb = new Transaction();
    await client.fastRouterSwap({
      router: routers,
      txb,
      slippage: 0.01,
      refreshAllCoins: true,
    });

    const result = await client.signAndExecuteTransaction(txb, keypair);
  } else {
    console.log("No routes found");
  }
} catch (error) {
  console.error("Swap execution failed:", error);
}

Complete Workflow Example

import { AggregatorClient, Env } from '@cetusprotocol/aggregator-sdk'
import { SuiClient } from '@mysten/sui/client'
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
import { Transaction } from '@mysten/sui/transactions'
import BN from 'bn.js'

async function executeOptimizedSwap() {
  // 1. Initialize client
  const mnemonics: string = process.env.MNEMONICS!;
  const keypair = Ed25519Keypair.deriveKeypair(mnemonics, `m/44'/784'/0'/0'/0'`);

  const suiClient = new SuiClient({ url: process.env.RPC! });
  const client = new AggregatorClient({
    signer: keypair.toSuiAddress(),
    client: suiClient,
    env: Env.Mainnet,
  });

  // 2. Find optimal routes
  const routers = await client.findRouters({
    from: "0x2::sui::SUI",
    target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
    amount: new BN(1000000000),
    byAmountIn: true,
    providers: ["CETUS", "KRIYA", "AFTERMATH"]
  });

  if (!routers) {
    console.log("No routes available");
    return;
  }

  // 3. Execute swap
  const txb = new Transaction();
  await client.fastRouterSwap({
    router: routers,
    txb,
    slippage: 0.01,
    refreshAllCoins: true,
  });

  const result = await client.signAndExecuteTransaction(txb, keypair);
  console.log("Swap completed:", result.digest);

  return result;
}

Dependencies

• @cetusprotocol/aggregator-sdk: ^1.4.2 (core SDK library)
• @mysten/sui: ^1.45.0 (Sui blockchain client)
• bn.js: ^5.2.0 (big number processing)
• TypeScript: ^5.0.0 (language support)

Support

If you encounter issues or have questions:

• Check the official Cetus documentation
• Check SDK error codes and messages
• Test on testnet before deploying to mainnet
• Monitor gas usage and adjust budgets accordingly

Skill Version: 1.0.0 Last Updated: 2025-11-25 Compatibility: Cetus Aggregator SDK v1.0+