Cetus Protocol SDK v2 - OpenClaw Integration Guide

Cetus Protocol SDK v2 - OpenClaw Integration Guide

This guide covers all Cetus SDK v2 packages for building DeFi applications on Sui.

Table of Contents

1. Common SDK
2. CLMM SDK
3. DLMM SDK
4. Vaults SDK
5. Farms SDK
6. xCETUS SDK
7. Limit Order SDK
8. Burn SDK
9. DCA SDK
10. Zap SDK
11. Aggregator SDK

Common SDK

Foundational utility library shared across all Cetus SDKs.

npm install @cetusprotocol/common-sdk

Provides essential utilities and shared functionality for protocol interactions. All other SDKs depend on this package.

CLMM SDK

Concentrated Liquidity Market Maker - the core AMM of Cetus.

npm install @cetusprotocol/sui-clmm-sdk

Initialization

import { CetusClmmSDK } from '@cetusprotocol/sui-clmm-sdk'

// Default mainnet
const sdk = CetusClmmSDK.createSDK()

// Custom environment
const sdk = CetusClmmSDK.createSDK({ env: 'mainnet' }) // or 'testnet'

// Custom RPC
const sdk = CetusClmmSDK.createSDK({ env: 'mainnet', full_rpc_url: 'YOUR_URL' })

// Custom SuiClient
const sdk = CetusClmmSDK.createSDK({ env: 'mainnet', sui_client: yourClient })

// Set sender address (required before tx operations)
sdk.setSenderAddress('YOUR_SUI_ADDRESS')

DLMM SDK

Dynamic Liquidity Market Maker - discrete bin-based AMM with dynamic fees.

npm install @cetusprotocol/dlmm-sdk

Initialization

import { CetusDlmmSDK } from '@cetusprotocol/dlmm-sdk'

const sdk = CetusDlmmSDK.createSDK()
// or with options: CetusDlmmSDK.createSDK({ env, full_rpc_url, sui_client })
sdk.setSenderAddress(walletAddress)

Pool Operations

// Get all pools
const pools = await sdk.Dlmm.getPoolList()

// Get specific pool
const pool = await sdk.Dlmm.getPool(pool_id)

// Get bin configuration
const binConfig = await sdk.Dlmm.getBinConfig(config_id)

// Get pool transaction history
const history = await sdk.Dlmm.getPoolTransactionHistory(pool_id)

Position Management

Three liquidity distribution strategies:

• Spot - even distribution across bins
• BidAsk - concentrated at specific price levels
• Curve - smooth bell-curve distribution

// Calculate optimal liquidity distribution
const addInfo = await sdk.Dlmm.calculateAddLiquidityInfo(params)

// Add liquidity
const payload = await sdk.Dlmm.addLiquidityPayload(params)

// Remove liquidity
const payload = await sdk.Dlmm.removeLiquidityPayload(params)

// Close position
const payload = await sdk.Dlmm.closePositionPayload(params)

Swap Operations

// Get swap quote
const quote = await sdk.Dlmm.preSwapQuote(params)

// Execute swap
const payload = await sdk.Dlmm.swapPayload(params)

Fee & Reward Operations

// Get total fee rate (base + variable)
const feeRate = await sdk.Dlmm.getTotalFeeRate(pool_id)

// Collect fees
const payload = await sdk.Dlmm.collectFeePayload(params)

// Collect rewards
const payload = await sdk.Dlmm.collectRewardPayload(params)

Pool Creation

// Create pool only
const payload = await sdk.Dlmm.createPoolPayload(params)

// Create pool + add initial liquidity
const payload = await sdk.Dlmm.createPoolAndAddLiquidityPayload(params)

Utility: BinUtils

import { BinUtils } from '@cetusprotocol/dlmm-sdk'

// Price-bin conversions
BinUtils.getPriceFromBinId(binId, binStep)
BinUtils.getBinIdFromPrice(price, binStep)

// Liquidity calculations
BinUtils.calculateLiquidity(params)

Vaults SDK

Automated liquidity management with fee reinvestment and rebalancing.

npm install @cetusprotocol/vaults-sdk

Initialization

import { CetusVaultsSDK } from '@cetusprotocol/vaults-sdk'

const sdk = CetusVaultsSDK.createSDK()
// or: CetusVaultsSDK.createSDK({ env, sui_client })
// or: CetusVaultsSDK.createSDK({ env, full_rpc_url })
sdk.setSenderAddress(wallet)

Vault Queries

// Get all vaults for an owner
const vaults = await sdk.Vaults.getOwnerVaultsBalance(owner)

// Get specific vault
const vault = await sdk.Vaults.getVault(vault_id)

// Get LP token balance
const balance = await sdk.getOwnerCoinBalances(address, lp_token_type)

Deposit

// Calculate deposit amounts
const amounts = await sdk.Vaults.calculateDepositAmount(params)

// Execute deposit
const tx = await sdk.Vaults.deposit(params, tx)

Withdraw

// Calculate withdrawal amounts
const amounts = await sdk.Vaults.calculateWithdrawAmount(params)

// Execute withdrawal
const tx = await sdk.Vaults.withdraw(params, tx)

Vesting

// Get vest info for multiple vaults
const vestInfoList = await sdk.Vest.getVaultsVestInfoList([vaultId])

// Get vest info for a single vault
const vestInfo = await sdk.Vest.getVaultsVestInfo(vault_id)

// Get user's vest NFTs
const nfts = await sdk.Vest.getOwnerVaultVestNFT(senderAddress)

// Redeem vested tokens
const payload = await sdk.Vest.buildRedeemPayload(options)

Farms SDK

Staking CLMM positions for additional reward farming.

npm install @cetusprotocol/farms-sdk

Initialization

import { CetusFarmsSDK } from '@cetusprotocol/farms-sdk'

const sdk = CetusFarmsSDK.createSDK()
// or: CetusFarmsSDK.createSDK({ env, sui_client })
sdk.setSenderAddress(wallet)

Pool Queries

// Get all farming pools
const pools = await sdk.Farms.getFarmsPoolList()

// Get specific pool
const pool = await sdk.Farms.getFarmsPool(pool_id)

// Get user's position NFTs
const nfts = await sdk.Farms.getOwnedFarmsPositionNFTList(wallet)

// Get specific NFT details
const nft = await sdk.Farms.getFarmsPositionNFT(position_nft_id)

Staking Operations

// Stake a CLMM position into farm
const payload = await sdk.Farms.depositPayload({ pool_id, clmm_position_id })

// Unstake position from farm
const payload = await sdk.Farms.withdrawPayload({ pool_id, position_nft_id })

// Harvest rewards
const payload = await sdk.Farms.harvestPayload({ pool_id, position_nft_id })

// Batch harvest + collect CLMM fees
const payload = await sdk.Farms.batchHarvestAndClmmFeePayload(farms_list, clmm_list)

Liquidity Operations (within Farm)

// Add liquidity with fixed coin amount
const payload = await sdk.Farms.addLiquidityFixCoinPayload(params)

// Remove liquidity
const payload = await sdk.Farms.removeLiquidityPayload(params)

// Claim fees and CLMM rewards
const payload = await sdk.Farms.claimFeeAndClmmReward({ pool_id, position_nft_id })

Error Codes

xCETUS SDK

Platform equity token management - convert CETUS to non-transferable xCETUS for governance and rewards.

npm install @cetusprotocol/xcetus-sdk

Initialization

import { CetusXcetusSDK } from '@cetusprotocol/xcetus-sdk'

const sdk = CetusXcetusSDK.createSDK({ env: 'mainnet', sui_client })
sdk.setSenderAddress(wallet)

Data Retrieval

// Get user's veNFT (holds xCETUS balance)
const veNFT = await sdk.Xcetus.getOwnerVeNFT()

// Get user's active locks
const locks = await sdk.Xcetus.getOwnerRedeemLockList()

// Get dividend manager info
const dividendMgr = await sdk.Xcetus.getDividendManager()

// Get veNFT dividend info
const dividendInfo = await sdk.Xcetus.getVeNFTDividendInfo()

// Get xCETUS manager (for ratio calculations)
const manager = await sdk.Xcetus.getXcetusManager()

Token Operations

// Convert CETUS -> xCETUS (1:1 ratio)
const payload = await sdk.Xcetus.convertPayload(params)

// Start lock-up redemption (xCETUS -> CETUS, time-locked)
const payload = await sdk.Xcetus.redeemLockPayload(params)

// Complete redemption after lock expires
const payload = await sdk.Xcetus.redeemPayload(params)

// Cancel active lock
const payload = await sdk.Xcetus.cancelRedeemPayload(params)

// Claim accumulated dividends
const payload = await sdk.Xcetus.redeemDividendV3Payload(params)

Utility Functions

// Calculate redeemable CETUS for given lock duration
const amount = sdk.Xcetus.redeemNum(lockDays, xCetusAmount)

// Reverse calculation
const xAmount = sdk.Xcetus.reverseRedeemNum(lockDays, cetusAmount)

// Get historical dividend data
const phaseInfo = await sdk.Xcetus.getPhaseDividendInfo(phase)

// Check lock status
import { XCetusUtil } from '@cetusprotocol/xcetus-sdk'
const isLocked = XCetusUtil.isLocked(lockObj)

Limit Order SDK

Place limit orders with specified price and expiration.

npm install @cetusprotocol/limit-sdk

Initialization

import { CetusLimitSDK } from '@cetusprotocol/limit-sdk'

const sdk = CetusLimitSDK.createSDK()
// or: CetusLimitSDK.createSDK({ env, sui_client })
sdk.setSenderAddress(wallet)

Order Management

// Place a limit order
const payload = await sdk.Limit.placeLimitOrder(params)
// params: coin types, amount, price, expiration

// Cancel running orders
const payload = await sdk.Limit.cancelOrdersByOwner(params)

// Claim completed order proceeds
const payload = await sdk.Limit.claimTargetCoin(params)

Order Queries

// Get order details
const order = await sdk.Limit.getLimitOrder(orderId)

// Get all orders for a wallet
const orders = await sdk.Limit.getOwnerLimitOrderList(address)

// Get order operation logs
const logs = await sdk.Limit.getLimitOrderLogs(orderId)

// Get claim logs
const claimLogs = await sdk.Limit.getLimitOrderClaimLogs(orderId)

Pool Info

// Get supported tokens
const tokens = await sdk.Limit.getLimitOrderTokenList()

// Get available pools
const pools = await sdk.Limit.getLimitOrderPoolList()

// Get specific pool
const pool = await sdk.Limit.getLimitOrderPool(coinA, coinB)

// Get pool indexer ID
const indexerId = await sdk.Limit.getPoolIndexerId(coinA, coinB)

Execution

// Execute transaction
await sdk.FullClient.executeTx(keyPair, payload, true)

Order statuses: Running | PartialCompleted | Completed | Cancelled

Burn SDK

Permanently lock liquidity positions while still earning fees and rewards.

npm install @cetusprotocol/burn-sdk

Initialization

import { CetusBurnSDK } from '@cetusprotocol/burn-sdk'

const sdk = CetusBurnSDK.createSDK()
// or: CetusBurnSDK.createSDK({ env, sui_client })
sdk.setSenderAddress(wallet)

Queries

// Get burn pool list
const pools = await sdk.Burn.getBurnPoolList()

// Get burn positions for a pool
const positions = await sdk.Burn.getPoolBurnPositionList(pool_id)

// Get burn positions for an account
const posIds = await sdk.Burn.getBurnPositionList(account_address)

// Get position details
const pos = await sdk.Burn.getBurnPosition(pos_id)

Burn Operations

// Lock liquidity permanently (irreversible!)
const payload = await sdk.Burn.createBurnPayload(params)

// Burn LP v2 (auto-validates, no pool object needed)
const payload = await sdk.Burn.createBurnLPV2Payload(pos_id)

Fee & Reward Collection (still works after burn)

// Collect fees for single position
const payload = await sdk.Burn.createCollectFeePayload(params)

// Collect rewards for single position
const payload = await sdk.Burn.createCollectRewardPayload(params)

// Batch collect fees for multiple positions
const payload = await sdk.Burn.createCollectFeesPayload(params)

// Batch collect rewards for multiple positions
const payload = await sdk.Burn.createCollectRewardsPayload(params)

Vesting

// Redeem vested tokens
const payload = await sdk.Burn.redeemVestPayload(params)
// params: versioned_id, vester_id, pool_data, period

DCA SDK

Dollar-Cost Averaging - automated periodic token purchases.

npm install @cetusprotocol/dca-sdk

Initialization

import { CetusDcaSDK } from '@cetusprotocol/dca-sdk'

const sdk = CetusDcaSDK.createSDK()
// or: CetusDcaSDK.createSDK({ env, sui_client })
sdk.setSenderAddress(wallet)

Order Management

// Create DCA order
const payload = await sdk.Dca.dcaOpenOrderPayload({
  // coin types, total amount, per-cycle amount,
  // cycle frequency, min/max price bounds
})

// Get order details
const order = await sdk.Dca.getDcaOrders(orderId)

// Get order transaction history
const deals = await sdk.Dca.getDcaOrdersMakeDeal(orderId)

// Withdraw from DCA order
const payload = await sdk.Dca.withdrawPayload(params)

// Close one or multiple DCA orders
const payload = await sdk.Dca.dcaCloseOrderPayload(params)

Token Whitelist

// Get supported tokens
const whitelist = await sdk.Dca.getDcaCoinWhiteList()

Whitelist modes:

Execution

await sdk.FullClient.sendTransaction(keyPair, payload)

Zap SDK

One-click liquidity operations - add/remove liquidity with flexible input modes.

npm install @cetusprotocol/zap-sdk

Initialization

import { CetusZapSDK } from '@cetusprotocol/zap-sdk'

const sdk = CetusZapSDK.createSDK()
// or: CetusZapSDK.createSDK({ env, sui_client, full_rpc_url })
sdk.setSenderAddress(wallet)

Deposit (Add Liquidity)

Deposit modes: FixedOneSide | FlexibleBoth | OnlyCoinA | OnlyCoinB

// Pre-calculate deposit amounts
const calcResult = await sdk.Zap.preCalculateDepositAmount({
  pool_id,
  tick_lower,
  tick_upper,
  current_sqrt_price,
  slippage,
  coin_type_a,
  coin_type_b,
  decimals_a,
  decimals_b,
  mode,
  amount_a, // or amount_b depending on mode
})

// Build and execute deposit
const payload = await sdk.Zap.buildDepositPayload({
  ...calcResult,
  // optional: existing position_id to add to
})

Withdraw (Remove Liquidity)

// Pre-calculate withdrawal amounts
const calcResult = await sdk.Zap.preCalculateWithdrawAmount(params)

// Build withdrawal transaction
const payload = await sdk.Zap.buildWithdrawPayload({
  ...calcResult,
  collect_fee: true,    // optionally collect fees
  collect_reward: true, // optionally collect rewards
})

Aggregator SDK

Multi-DEX swap aggregator optimizing trades across Cetus, DeepBook, Kriya, FlowX, Aftermath, and more.

npm install @cetusprotocol/aggregator-sdk

Workflow

import { CetusAggregatorSDK } from '@cetusprotocol/aggregator-sdk'

// Step 1: Initialize client
const client = CetusAggregatorSDK.createSDK({
  env: 'mainnet',
  // RPC and package config
})

// Step 2: Find optimal route
const routes = await client.findRouters({
  coinTypeFrom,
  coinTypeTo,
  amount,
})

// Step 3a: Fast swap (simple)
const result = await client.fastRouterSwap({
  routes,
  slippage, // e.g. 0.01 for 1%
  keyPair,
})

// Step 3b: Build PTB transaction (advanced)
const tx = await client.routerSwap({
  routes,
  slippage,
  // manage coin transfers manually
})

Supported DEXs

Cetus, DeepBook, Kriya, FlowX, Aftermath, Turbos, Bluefin, and more.

Mainnet Contract Addresses

• CetusAggregatorV2 - Primary aggregator
• CetusAggregatorV2ExtendV1 - Extended functionality
• CetusAggregatorV2ExtendV2 - Extended functionality v2

Common Patterns

SDK Initialization (all packages follow this pattern)

// Default mainnet
const sdk = Cetus<Module>SDK.createSDK()

// Custom env
const sdk = Cetus<Module>SDK.createSDK({ env: 'testnet' })

// Custom RPC
const sdk = Cetus<Module>SDK.createSDK({ env: 'mainnet', full_rpc_url: 'YOUR_URL' })

// Custom SuiClient
const sdk = Cetus<Module>SDK.createSDK({ env: 'mainnet', sui_client: yourClient })

// Always set sender before transactions
sdk.setSenderAddress('0x...')

// Update RPC at runtime
sdk.updateFullRpcUrl('NEW_URL')

Transaction Execution

// Using FullClient
await sdk.FullClient.executeTx(keyPair, payload, true)

// Or sendTransaction
await sdk.FullClient.sendTransaction(keyPair, payload)

Package Reference