# @cetusprotocol/dlmm-sdk 中文文档

规范地址：https://npmcn.com/package/%40cetusprotocol/dlmm-sdk/

版本：1\.3\.3
npm 元数据更新时间：2026-10-01T04:56:28.730Z
中文译文更新时间：2026-11-09T15:15:25.508Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cetusprotocol/dlmm-sdk
原文对照：https://npmcn.com/package/%40cetusprotocol/dlmm-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：909 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：blakejs \*，@mysten/sui \>=2\.28\.0，@cetusprotocol/common-sdk \*
- 首次发布：2025-09-15T09:49:22.448Z
- 最新版本发布：2026-10-01T04:56:28.549Z
- 近 30 天下载量：2387（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 46 个）

## 中文简介

Cetus dlmm 的 SDK 定义

## 安装

```sh
npm install @cetusprotocol/dlmm-sdk
```

也可以使用：`pnpm add @cetusprotocol/dlmm-sdk`、`yarn add @cetusprotocol/dlmm-sdk`、`bun add @cetusprotocol/dlmm-sdk`

## README

# @cetusprotocol/dlmm-sdk

SDK提供DLMM(Dynamic Liquidity Market Maker)模块,用于具有不同模式的专门流动性业务,以适应各种交易策略. 这个模块使用户能够灵活地进行复杂的流动资金业务,以管理其职位.

## 特征

-   **多重流动性战略**: Spot、BidAsk和各种贸易办法的曲线战略
-   **综合池管理**: 创建、查询和管理 DLMM 池
-   **高级职位管理**: 增加/转移流动资金、收取费用和奖励
-   **灵活交换操作**: 支持A对B和B对A互换
-   **伙伴融合**: 内设伙伴和转介系统
-   **丰富的功能**: Bin计算、价格转换和流动性管理工具
-   **多网络支持**: 主网和测试网的工程

## 开始

## 如何使用 DLMM SDK ?

### 安装

开始使用 `DLMM SDK`,您首先需要在您的 TypeScript 项目中安装:

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

### 设置

将 SDK 导入到您打算使用的 TypeScript 文件 :

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

### 初始化 SDK

以所需的配置参数初始化 SDK. 这通常包括在必要时建立网络.

**选项1: 使用默认主网配置**

```typescript
const sdk = CetusDlmmSDK.createSDK()
```

**备选案文2:指定网络环境**

```typescript
// For mainnet
const sdk = CetusDlmmSDK.createSDK({ env: 'mainnet' })

// For testnet
const sdk = CetusDlmmSDK.createSDK({ env: 'testnet' })
```

**选项3:使用自定义 RPC URL**

```typescript
const sdk = CetusDlmmSDK.createSDK({ 
  env: 'mainnet',
  full_rpc_url: 'YOUR_FULL_NODE_URL' 
})
```

**选项4:使用自定义 SuiGrpcClient**

```typescript
import { SuiGrpcClient } from '@mysten/sui/client'

const suiClient = new SuiGrpcClient({ url: 'YOUR_RPC_URL' })
const sdk = CetusDlmmSDK.createSDK({ env: 'mainnet', sui_client: suiClient })
```

## 使用量

连接钱包后,如果需要使用钱包地址来做某事,应当设置在 `sdk.setSenderAddress`。 。 。 .

```typescript
const wallet = 'YOUR_WALLET_ADDRESS'
sdk.setSenderAddress(wallet)
```

如果您需要更改您的 RPC URL, 您可以按以下方式进行 :

```typescript
const new_rpc_url = 'YOUR_NEW_FULL_NODE_URL'
sdk.updateFullRpcUrl(new_rpc_url)
```

### 共同参数

-   `pool_id`: 流动性池的标识
-   `bin_id`: 池中垃圾桶的标识
-   `bin_step`: 垃圾桶之间的步骤大小
-   `coin_type_a` 打开 `coin_type_b`: 交易配对的硬币类型标识符
-   `coin_decimal_a` 打开 `coin_decimal_b`: 每种硬币的十进制位置

### 默认收费选项

SDK为不同类型的交易配对提供预定义的收费配置. 这些配置根据资产波动和市场特点得到优化:

```typescript
const dlmmDefaultFeeOptions = [
  { binStep: 1, baseFactor: 10000, fee: '0.0001' },
  { binStep: 1, baseFactor: 20000, fee: '0.0002' },
  { binStep: 2, baseFactor: 15000, fee: '0.0003' },
  { binStep: 2, baseFactor: 20000, fee: '0.0004' },
  { binStep: 5, baseFactor: 10000, fee: '0.0005' },
  { binStep: 10, baseFactor: 10000, fee: '0.001' },
  { binStep: 15, baseFactor: 10000, fee: '0.0015' },
  { binStep: 20, baseFactor: 10000, fee: '0.002' },
  { binStep: 25, baseFactor: 10000, fee: '0.0025' },
  { binStep: 30, baseFactor: 10000, fee: '0.003' },
  { binStep: 50, baseFactor: 8000, fee: '0.004' },
  { binStep: 80, baseFactor: 7500, fee: '0.006' },
  { binStep: 100, baseFactor: 8000, fee: '0.008' },
  { binStep: 100, baseFactor: 10000, fee: '0.01' },
  { binStep: 200, baseFactor: 10000, fee: '0.02' },
  { binStep: 400, baseFactor: 10000, fee: '0.04' }
]
```

**参数解释:**

-   **`binStep`**:宾馆之间的阶梯尺寸,确定池子的价格颗粒. 更小的数值提供了更细小的价格分辨率,但需要更多的计算资源.
-   **`baseFactor`**: 收费计算中使用的乘数,会影响池的整体收费结构.
-   **`fee`**: 十进制交易收费率(如"0.0001"=0.01%). 这是每次互换交易收取的费用.

**收费等级建议:**

-   **低收费(0.01%-0.05%)**: 稳定配对或低挥发性主流资产的最佳
-   **中等费用(0.1% - 0.3%)**: 适用于中等挥发性资产或主流交易配对
-   **高收费(0.4%-4%)**: 推荐高挥发性资产、代币或小市场上限配对

在创建新池时, 请选择最符合您交易配对特性的收费配置 :

```typescript
// Example: Create a pool for a stable pair (USDC/USDT)
const stablePairConfig = { binStep: 1, baseFactor: 10000, fee: '0.0001' }

// Example: Create a pool for a volatile altcoin pair
const altcoinConfig = { binStep: 100, baseFactor: 10000, fee: '0.01' }
```

### 1\. 集合业务

#### 获取池信息

```typescript
// Get all pools
const pools = await sdk.Pool.getPools()

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

// Get specific pools by their IDs
const assign_pools = await sdk.Pool.getAssignPoolList([
  '0x...',
  // Add more pool IDs as needed
])

// Get bin information
const bin_info = await sdk.Pool.getBinInfo(pool_id, bin_id, bin_step)

// Get pool bin information
const pool_bin_info = await sdk.Pool.getPoolBinInfo(pool_id)

// Get bin step configurations
const bin_step_configs = await sdk.Pool.getBinStepConfigs()

// Get pool transaction list
const pool_transactions = await sdk.Pool.getPoolTransactionList({
  pool_id: '0x...',
  pagination_args: { limit: 10 }
})
```

#### 创建池

创建池有两种方式:

**方法 1: 只创建池**

```typescript
// Create a new pool without adding liquidity
const bin_step = 2
const base_factor = 10000
const price = '1.1'
const active_id = BinUtils.getBinIdFromPrice(price, bin_step, true, 6, 6)

const tx = new Transaction()
await sdk.Pool.createPoolPayload({
  active_id,
  bin_step,
  coin_type_a: '0x...::usdc::USDC',
  coin_type_b: '0x...::usdt::USDT',
  base_factor,
}, tx)
```

**方法2:在一个交易中创建集合并添加流动性**

```typescript
// Create pool and add liquidity in one transaction
const bin_step = 2
const base_factor = 10000
const price = '1.1'
const active_id = BinUtils.getBinIdFromPrice(price, bin_step, true, 6, 6)

// Calculate liquidity distribution
const bin_infos = sdk.Position.calculateAddLiquidityInfo({
  active_id,
  bin_step,
  lower_bin_id: active_id - 10,
  upper_bin_id: active_id + 10,
  amount_a_in_active_bin: '0',
  amount_b_in_active_bin: '0',
  strategy_type: StrategyType.Spot,
  coin_amount: '10000000',
  fix_amount_a: true,
})

const createAndAddTx = await sdk.Pool.createPoolAndAddLiquidityPayload({
  active_id,
  lower_bin_id: active_id - 10,
  upper_bin_id: active_id + 10,
  bin_step,
  bin_infos,
  coin_type_a: '0x14a71d857b34677a7d57e0feb303df1adb515a37780645ab763d42ce8d1a5e48::usdc::USDC',
  coin_type_b: '0x14a71d857b34677a7d57e0feb303df1adb515a37780645ab763d42ce8d1a5e48::eth::ETH',
  strategy_type: StrategyType.Spot,
  use_bin_infos: false,
  base_factor,
})
```

### 2\. 职位业务

#### 获取位置信息

```typescript
// Get owner's position list
const positions = await sdk.Position.getOwnerPositionList(wallet)

// Get specific position
const position = await sdk.Position.getPosition(position_id)
```

### 3\. 收费业务

#### 收费和报酬计算

为了计算职位的收费和奖励,您可以使用 `fetchPositionFeeAndReward` 方法。 此方法允许您同时获得一个或多个职位的收费和奖励数据:

```typescript
// First get the pool information
const pool = await sdk.Pool.getPool(pool_id)
const { id, coin_type_a, coin_type_b, reward_manager } = pool

// Fetch fee and reward data
const { feeData, rewardData } = await sdk.Position.fetchPositionFeeAndReward([
  {
    pool_id: id,
    position_id: position_id,
    reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
    coin_type_a,
    coin_type_b,
  },
])

```

#### 费率计算

```typescript
// Get total fee rate for a pool
const totalFeeRate = await sdk.Pool.getTotalFeeRate({
  pool_id,
  coin_type_a,
  coin_type_b
})

// Get variable fee from pool parameters
const variableFee = FeeUtils.getVariableFee(pool.variable_parameters)
console.log('Variable fee:', variableFee)
console.log('Variable fee percentage:', d(variableFee).div(d(FEE_PRECISION)).toString())
```

**获取总计返回值**

这个 `getTotalFeeRate` 方法返回 a `FeeRate` 包含下列字段的天体:

```typescript
type FeeRate = {
  base_fee_rate: string    // Base fee rate
  var_fee_rate: string     // Variable fee rate
  total_fee_rate: string   // Total fee rate
}
```

**字段描述 :**

-   **`base_fee_rate`**: 基费标准,从池中计算 `bin_step` 财务报告和审定财务报表 `base_factor`,是一个固定值
-   **`var_fee_rate`**:可变费率,根据池的起伏累积器动态计算(`volatility_accumulator`),随着市场波动而变化
-   **`total_fee_rate`**: 总费率等值 `base_fee_rate + var_fee_rate`,但不超过最高费率限额(`MAX_FEE_RATE = 100,000,000`(中文(简体) )

**收费率精度 :**

-   所有费率价值 `FEE_PRECISION = 1,000,000,000` 作为精度单位
-   要获得实际百分比,将收费率除以 `FEE_PRECISION`
-   示例:如果 `total_fee_rate` 实值 `3000000`,实际费率为 `3000000 / 1000000000 = 0.003 = 0.3%`

**用法示例:**

```typescript
const feeRate = await sdk.Pool.getTotalFeeRate({
  pool_id: "0x...",
  coin_type_a: "0x...",
  coin_type_b: "0x..."
})

// Calculate actual percentages
const baseFeePercentage = d(feeRate.base_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()
const varFeePercentage = d(feeRate.var_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()
const totalFeePercentage = d(feeRate.total_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()

console.log(`Base fee rate: ${baseFeePercentage}%`)
console.log(`Variable fee rate: ${varFeePercentage}%`)
console.log(`Total fee rate: ${totalFeePercentage}%`)
```

#### 收费工具方法

这个 `FeeUtils` 类为计算费用提供了几种实用方法:

**1\. 联合国. `getVariableFee(variableParameters: VariableParameters): string`**

根据集合参数和市场波动来计算可变收费.

```typescript
import { FeeUtils } from '@cetusprotocol/dlmm-sdk'

const variableFee = FeeUtils.getVariableFee(pool.variable_parameters)
console.log('Variable fee:', variableFee)
console.log('Variable fee percentage:', d(variableFee).div(d(FEE_PRECISION)).toString())
```

**2\. 联合国. `calculateCompositionFee(amount: string, total_fee_rate: string): string`**

计算流动性业务的组成费.

```typescript
const compositionFee = FeeUtils.calculateCompositionFee(amount, total_fee_rate)
```

**3个. `calculateProtocolFee(fee_amount: string, protocol_fee_rate: string): string`**

根据费用数额和协议费计算协议费.

```typescript
const protocolFee = FeeUtils.calculateProtocolFee(fee_amount, protocol_fee_rate)
```

**4.四. `getProtocolFees(fee_a: string, fee_b: string, protocol_fee_rate: string)`**

计算两个令牌的一对协议费.

```typescript
const { protocol_fee_a, protocol_fee_b } = FeeUtils.getProtocolFees(fee_a, fee_b, protocol_fee_rate)
console.log('Protocol fee A:', protocol_fee_a)
console.log('Protocol fee B:', protocol_fee_b)
```

**5 (韩语). `getCompositionFees(active_bin: BinAmount, used_bin: BinAmount, variableParameters: VariableParameters)`**

考虑到可变参数,计算活动箱和使用箱的构成费.

```typescript
const { fees_a, fees_b } = FeeUtils.getCompositionFees(active_bin, used_bin, variableParameters)
console.log('Composition fees A:', fees_a)
console.log('Composition fees B:', fees_b)
```

**收费单位方法摘要 :**

| 方法 | 说明 | 参数 | 回返 |
| --- | --- | --- | --- |
| `getVariableFee` | 从集合参数计算可变费用 | `variableParameters` | `string` |
| `calculateCompositionFee` | 计算某一数额的构成费 | `amount`, (中文(简体) ), `total_fee_rate` | `string` |
| `calculateProtocolFee` | 计算协议费 | `fee_amount`, (中文(简体) ), `protocol_fee_rate` | `string` |
| `getProtocolFees` | 计算两个令牌的协议费 | `fee_a`, (中文(简体) ), `fee_b`, (中文(简体) ), `protocol_fee_rate` | `{protocol_fee_a, protocol_fee_b}` |
| `getCompositionFees` | 计算垃圾箱的组装费 | `active_bin`, (中文(简体) ), `used_bin`, (中文(简体) ), `variableParameters` | `{fees_a, fees_b}` |

#### 收费和奖励

您可通过多种方式从岗位上收取费用:

1.  **收费和奖励**数字 :

```typescript
// Build collect fee and reward transaction
const tx = await sdk.Position.collectRewardAndFeePayload([{
  pool_id,
  position_id,
  reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
  coin_type_a,
  coin_type_b
}])

// Simulate or send the transaction
const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
```

### 4\. 流动性业务

#### 添加流动性

DLMM SDK提供了两种增加流动性的主要方法:

1.  **`calculateAddLiquidityInfo(option)`** - 计算各垃圾箱之间的流动资金分布
2.  **`addLiquidityPayload(option, tx?)`** - 创建交易有效载荷来增加流动性

**方法1: `calculateAddLiquidityInfo(option: CalculateAddLiquidityOption | CalculateAddLiquidityAutoFillOption)`**

这种方法根据您的策略和参数计算流动性应如何在不同的垃圾箱之间分配.

**参数 `CalculateAddLiquidityOption`数字 :**

```typescript
interface CalculateAddLiquidityOption {
  pool_id: string                    // Pool ID
  amount_a: string                   // Amount of token A to add
  amount_b: string                   // Amount of token B to add
  active_id: number                  // Current active bin ID
  bin_step: number                   // Bin step size
  lower_bin_id: number               // Lower bound of bin range
  upper_bin_id: number               // Upper bound of bin range
  active_bin_of_pool?: {             // Active bin amounts (if active bin is in range)
    amount_a: string
    amount_b: string
  }
  strategy_type: StrategyType        // Liquidity strategy (Spot, BidAsk, Curve)
}
```

**参数 `CalculateAddLiquidityAutoFillOption`数字 :**

```typescript
interface CalculateAddLiquidityAutoFillOption {
  pool_id: string                    // Pool ID
  coin_amount: string                // Fixed amount of one token
  fix_amount_a: boolean              // true for token A, false for token B
  active_id: number                  // Current active bin ID
  bin_step: number                   // Bin step size
  lower_bin_id: number               // Lower bound of bin range
  upper_bin_id: number               // Upper bound of bin range
  active_bin_of_pool?: {             // Active bin amounts (if active bin is in range)
    amount_a: string
    amount_b: string
  }
  strategy_type: StrategyType        // Liquidity strategy (Spot, BidAsk, Curve)
}
```

**方法2: `addLiquidityPayload(option: AddLiquidityOption | OpenAndAddLiquidityOption, tx?: Transaction)`**

这种方法创造了交易有效载荷,用于将流动性添加到现有位置或打开新位置.

**参数 `AddLiquidityOption` (现有职位):**

```typescript
interface AddLiquidityOption {
  pool_id: string                    // Pool ID
  bin_infos: BinLiquidityInfo        // Calculated bin distribution from calculateAddLiquidityInfo
  coin_type_a: string                // Token A coin type
  coin_type_b: string                // Token B coin type
  active_id: number                  // Current active bin ID
  position_id: string                // Existing position ID
  collect_fee: boolean               // Whether to collect fees
  reward_coins: string[]             // Reward coin types
  strategy_type: StrategyType        // Liquidity strategy
  use_bin_infos: boolean             // Whether to use calculated bin_infos
  max_price_slippage: number         // Maximum price slippage tolerance
  bin_step: number                   // Bin step size
}
```

**参数 `OpenAndAddLiquidityOption` (新职位):**

```typescript
interface OpenAndAddLiquidityOption {
  pool_id: string                    // Pool ID
  bin_infos: BinLiquidityInfo        // Calculated bin distribution from calculateAddLiquidityInfo
  coin_type_a: string                // Token A coin type
  coin_type_b: string                // Token B coin type
  lower_bin_id: number               // Lower bound of bin range
  upper_bin_id: number               // Upper bound of bin range
  active_id: number                  // Current active bin ID
  strategy_type: StrategyType        // Liquidity strategy
  use_bin_infos: boolean             // Whether to use calculated bin_infos
  max_price_slippage: number         // Maximum price slippage tolerance
  bin_step: number                   // Bin step size
}
```

**完整示例 - 在现有位置上添加流动性:**

```typescript
// Step 1: Calculate liquidity distribution
const calculateOption: CalculateAddLiquidityOption = {
  pool_id: '0x...',
  amount_a: '1000000',
  amount_b: '1200000',
  active_id: 100,
  bin_step: 2,
  lower_bin_id: 90,
  upper_bin_id: 110,
  active_bin_of_pool: amounts_in_active_bin, // Optional: if active bin is in range
  strategy_type: StrategyType.Spot
}

const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)

// Step 2: Create transaction payload
const addLiquidityOption: AddLiquidityOption = {
  pool_id: '0x...',
  bin_infos: bin_infos,
  coin_type_a: '0x...::usdc::USDC',
  coin_type_b: '0x...::usdt::USDT',
  active_id: 100,
  position_id: '0x...',
  collect_fee: true,
  reward_coins: [],
  strategy_type: StrategyType.Spot,
  use_bin_infos: false,
  max_price_slippage: 0.01,
  bin_step: 2
}

const tx = sdk.Position.addLiquidityPayload(addLiquidityOption)
```

**完整示例 - 打开新位置 :**

```typescript
// Step 1: Calculate liquidity distribution
const calculateOption: CalculateAddLiquidityOption = {
  pool_id: '0x...',
  amount_a: '1000000',
  amount_b: '1200000',
  active_id: 100,
  bin_step: 2,
  lower_bin_id: 90,
  upper_bin_id: 110,
  active_bin_of_pool: amounts_in_active_bin,
  strategy_type: StrategyType.Spot
}

const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)

// Step 2: Create transaction payload for new position
const openPositionOption: OpenAndAddLiquidityOption = {
  pool_id: '0x...',
  bin_infos: bin_infos,
  coin_type_a: '0x...::usdc::USDC',
  coin_type_b: '0x...::usdt::USDT',
  lower_bin_id: 90,
  upper_bin_id: 110,
  active_id: 100,
  strategy_type: StrategyType.Spot,
  use_bin_infos: false,
  max_price_slippage: 0.01,
  bin_step: 2
}

const tx = sdk.Position.addLiquidityPayload(openPositionOption)
```

**重要参数注释:**

-   **`active_bin_of_pool`**: 当活性垃圾桶落在您的位置范围内时, 此参数至关重要 。 使用 `getActiveBinIfInRange()` 以获取正确的值.
-   **`use_bin_infos`**: 当 `false`,合同在内部计算流动性分配 `true`,它使用提供的 `bin_infos`。 。 。 .
-   **`max_price_slippage`**:在交易执行过程中防止价格波动(如0.01=1%的滑行容忍度).
-   **`collect_fee`**:仅适用于现有职位;确定在增加流动资金时是否收取累积费用.
-   **`strategy_type`**: 影响流动资金如何在垃圾箱之间分配:
    -   `Spot`: 甚至按时价分配
    -   `BidAsk`: 集中在特定价格水平
    -   `Curve`: 曲线后平滑分布

增加流动性有三种战略:Spot、BidAsk和Curve。 下面是使用每个:

1.  **点点战略**数字 :

```typescript
// Get pool information
const pool = await sdk.Pool.getPool(pool_id)
const { active_id, bin_step, bin_manager } = pool

// Get amounts in active bin if it's within the range
const amounts_in_active_bin = await sdk.Position.getActiveBinIfInRange(
  bin_manager.bin_manager_handle,
  lower_bin_id,
  upper_bin_id,
  active_id,
  bin_step
)

// Calculate liquidity distribution
const calculateOption = {
  pool_id,
  amount_a: '1000000',
  amount_b: '1200000',
  active_id,
  bin_step,
  lower_bin_id: -10,
  upper_bin_id: 10,
  amount_a_in_active_bin: amounts_in_active_bin?.amount_a || '0',
  amount_b_in_active_bin: amounts_in_active_bin?.amount_b || '0',
  strategy_type: StrategyType.Spot
}
const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)

// For new position
const addOption = {
  pool_id,
  amount_a,
  amount_b,
  active_id,
  bin_step,
  lower_bin_id,
  upper_bin_id,
  active_bin_of_pool: amounts_in_active_bin,
  strategy_type: StrategyType.Spot,
}
const tx = sdk.Position.addLiquidityPayload(addOption)

// For existing position
const addOption = {
  pool_id,
  bin_infos: bin_infos,
  coin_type_a,
  coin_type_b,
  active_id,
  position_id,
  collect_fee: true,
  reward_coins: [],
  strategy_type: StrategyType.Spot,
  use_bin_infos: false,
  max_price_slippage: 0.01,
  bin_step,
}
const tx = sdk.Position.addLiquidityPayload(addOption)
```

说明: `amount_a_in_active_bin` 财务报告和审定财务报表 `amount_b_in_active_bin` 参数用于计算在您位置范围内的正态流动资金分布。 这些值是使用下列方法获得的: `getActiveBinIfInRange` 方法,该方法:

1.  检查活动本是否在指定范围内
2.  如果在活动框内, 返回这两个符号的金额
3.  返回未定义的已激活的 bin 在区域外

* * *

2.  **投标战略**数字 :

```typescript
// Similar to Spot strategy but with different strategy_type
const calculateOption = {
  amount_a: '1000000',
  amount_b: '1200000',
  active_id,
  bin_step,
  lower_bin_id: -10,
  upper_bin_id: 10,
  amount_a_in_active_bin: '0',
  amount_b_in_active_bin: '0',
  strategy_type: StrategyType.BidAsk
}
```

3.  **曲线策略**数字 :

```typescript
// Similar to Spot strategy but with different strategy_type
const calculateOption = {
  amount_a: '1000000',
  amount_b: '1200000',
  active_id,
  bin_step,
  lower_bin_id: -10,
  upper_bin_id: 10,
  amount_a_in_active_bin: '0',
  amount_b_in_active_bin: '0',
  strategy_type: StrategyType.Curve
}
```

4.  **固定数额战略**数字 :

```typescript
// Calculate with fixed amount of one token
const calculateOption = {
  coin_amount: '1000000',
  fix_amount_a: true, // true for token A, false for token B
  active_id,
  bin_step,
  lower_bin_id: -10,
  upper_bin_id: 10,
  amount_a_in_active_bin: '0',
  amount_b_in_active_bin: '0',
  strategy_type: StrategyType.Spot // or BidAsk or Curve
}
```

5.  **添加流动性与价格**数字 :

```typescript
// Add liquidity with specific price range
const addOption = {
  pool_id,
  bin_infos,
  coin_type_a: pool.coin_type_a,
  coin_type_b: pool.coin_type_b,
  price_base_coin: 'coin_a',
  price: price.toString(),
  lower_price,
  upper_price,
  bin_step,
  amount_a_in_active_bin: amounts_in_active_bin?.amount_a || '0',
  amount_b_in_active_bin: amounts_in_active_bin?.amount_b || '0',
  strategy_type: StrategyType.Spot,
  decimals_a: 6,
  decimals_b: 6,
  max_bin_slippage: 0.01,
  active_id,
  // If use_bin_infos is true, liquidity is allocated according to bin_infos; otherwise, it is calculated internally by the contract
  use_bin_infos: false,
}
const tx = sdk.Position.addLiquidityWithPricePayload(addOption)
```

#### 删除流动性

有两种方法可以消除流动性:

1.  **随两个数量一起删除**数字 :

```typescript
// Get position and pool information
const pool = await sdk.Pool.getPool(pool_id)
const position = await sdk.Position.getPosition(position_id)
const { active_id, bin_step, bin_manager } = pool

// Get active bin information
const active_bin = await sdk.Pool.getBinInfo(bin_manager.bin_manager_handle, active_id, bin_step)
const liquidity_shares_data = parseLiquidityShares(position.liquidity_shares, bin_step, position.lower_bin_id, active_bin)

// Calculate removal amounts
const calculateOption = {
  bins: liquidity_shares_data.bins,
  active_id,
  fix_amount_a: true,
  coin_amount: '100000'
}
const bin_infos = sdk.Position.calculateRemoveLiquidityInfo(calculateOption)

// Build and send transaction
const removeOption = {
  pool_id,
  bin_infos,
  coin_type_a: pool.coin_type_a,
  coin_type_b: pool.coin_type_b,
  position_id,
  active_id,
  slippage: 0.01,
  reward_coins: []，
  collect_fee: true,
  reward_coins: [],
  bin_step,
  remove_percent: 0.5, // If remove_percent is specified, bin_infos will not be effective
}
const tx = sdk.Position.removeLiquidityPayload(removeOption)
```

2.  **只删除一个托肯**数字 :

```typescript
const calculateOption = {
  bins: liquidity_shares_data.bins,
  active_id,
  is_only_a: true, // true for token A, false for token B
  coin_amount: '100000'
}
```

#### 关闭位置

```typescript
// Close position (This will collect all fees, rewards and remove all liquidity)
const tx = sdk.Position.closePositionPayload({
  pool_id,
  position_id,
  coin_type_a,
  coin_type_b,
  reward_coins: pool.reward_manager.rewards.map(reward => reward.reward_coin) // Required: Must include all reward coin types from the pool
})

// Simulate or send the transaction
const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
```

注: 结束职位将:

1.  收取所有累计费用
2.  收集所有待定的奖赏(必须包括池中的所有奖赏硬币)
3.  从位置移除全部流动性
4.  删除该位置

### 5\. 交换业务

```typescript
// Get pool information
const pool = await sdk.Pool.getPool(pool_id)
const { coin_type_a, coin_type_b } = pool

// Get swap quote
const quote_obj = await sdk.Swap.preSwapQuote({
  pool_id,
  a2b: true, // true for A to B, false for B to A
  by_amount_in: true, // true for exact input, false for exact output
  in_amount: '2000000',
  coin_type_a,
  coin_type_b
})

// Build and send swap transaction
const tx = sdk.Swap.swapPayload({
  coin_type_a,
  coin_type_b,
  quote_obj,
  by_amount_in: true,
  slippage: 0.01
})
```

### 6\. 伙伴业务

#### 伙伴管理

```typescript
// Get partner list
const partnerList = await sdk.Partner.getPartnerList()

// Get specific partner
const partner = await sdk.Partner.getPartner(partner_id)

// Get partner capability ID
const partnerCapId = await sdk.Partner.getPartnerCapId(account, partner_id)

// Get partner balance
const partnerBalance = await sdk.Partner.getPartnerBalance(partner_id)

// Create partner
const start_time = Math.floor(Date.now() / 1000) + 5000
const tx = sdk.Partner.createPartnerPayload({
  name: 'test partner',
  ref_fee_rate: 0.01,
  start_time,
  end_time: start_time + 9 * 24 * 3600,
  recipient: account,
})

// Update referral fee rate
const updateFeeTx = await sdk.Partner.updateRefFeeRatePayload({
  partner_id: '0x..',
  ref_fee_rate: 0.02,
})

// Update time range
const start_time = Math.floor(Date.now() / 1000)
const updateTimeTx = await sdk.Partner.updateTimeRangePayload({
  partner_id: '0x..',
  start_time,
  end_time: start_time + 10 * 7 * 24 * 3600,
})

// claim ref fee
const tx = await sdk.Position.claimRefFeePayload({
  partner_id: "0x..",
  partner_cap_id: "0x..", // Optional parameter
  fee_coin_types: [coin_type]
})

// Simulate or send the transaction
const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)

```

### 7\. 奖励业务

#### 奖励管理

```typescript
// Initialize rewards for a pool
const initTx = sdk.Reward.initRewardPayload({
  pool_id,
  reward_coin_types: ['0x2::sui::SUI', '0x5::usdc::USDC']
})

// Add reward to a pool
const addRewardTx = sdk.Reward.addRewardPayload({
  pool_id,
  reward_coin_type: '0x2::sui::SUI',
  reward_amount: '1000000',
  end_time_seconds: Math.floor(Date.now() / 1000) + 30 * 24 * 3600, // 30 days
  start_time_seconds: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
})

// Update reward access (public/private)
const accessTx = sdk.Reward.updateRewardAccessPayload({
  pool_id,
  type: 'to_public', // or 'to_private'
})

// Manage reward whitelist
const whitelistTx = sdk.Reward.updateRewardWhiteListPayload({
  reward_coin_types: ['0x2::sui::SUI'],
  type: 'add' // or 'remove'
})
```

### 8\. 配置管理

SDK 通过 `Config` 模块 :

```typescript
// Get global DLMM configuration
const globalConfig = await sdk.Config.getDlmmGlobalConfig()

// Get bin step configuration list
const binStepConfigs = await sdk.Config.getBinStepConfigList(pool_id)

// Fetch all SDK configurations
const sdkConfigs = await sdk.Config.fetchDlmmSdkConfigs()

// Get reward period emission data
const rewardEmission = await sdk.Reward.getRewardPeriodEmission(
  reward_manager_id,
  reward_period,
  current_time
)
```

### 9\. 本业务

SDK提供综合的公用功能,以通过 `BinUtils` 类 :

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

// Convert price to bin ID
const binId = BinUtils.getBinIdFromPrice(
  '1040.07',  // price
  2,          // bin step
  true,       // is base coin A
  6,          // decimals for coin A
  9           // decimals for coin B
)

// Convert bin ID to price
const price = BinUtils.getPriceFromBinId(
  -4787,      // bin ID
  2,          // bin step
  6,          // decimals for coin A
  9           // decimals for coin B
)

// Get Q price from bin ID
const q_price = BinUtils.getQPriceFromId(
  -4400,      // bin ID
  100         // bin step
)

// Get price per lamport from Q price
const price_per_lamport = BinUtils.getPricePerLamportFromQPrice(q_price)

// Get liquidity from amounts
const liquidity = BinUtils.getLiquidity('0', '266666', '18431994054197767090')

// Get amount A from liquidity
const amountA = BinUtils.getAmountAFromLiquidity('4101094304427826916657468', '18461505896777422276')

// Get amount B from liquidity
const amountB = BinUtils.getAmountBFromLiquidity('4919119455159831291232256')


// Split bin liquidity info
const split_bin_infos = BinUtils.splitBinLiquidityInfo(bin_infos, 0, 70)

// Get position count between bin ranges
const positionCount = BinUtils.getPositionCount(-750, 845)

// Find min/max bin ID for a given bin step
const { minBinId, maxBinId } = BinUtils.findMinMaxBinId(10)
```

这些公用事业功能在下列情况下特别有用:

-   确定流动性头寸的价格幅度
-   计算交易战略的最佳宾站范围
-   在不同的价格表述之间转换
-   二. 管理各垃圾箱之间的流动资金分配
-   分析位置密度和分布

### 9\. 高级业务

#### 验证活动 ID 剪贴页

```typescript
// Validate that the active ID hasn't moved too much
const isValid = await sdk.Position.validateActiveIdSlippage({
  pool_id,
  active_id,
  max_bin_slippage: 0.01
})
```

#### 更新职位费和奖励

```typescript
// Update position fee and reward information
await sdk.Position.updatePositionFeeAndRewards({
  pool_id,
  position_id,
  coin_type_a,
  coin_type_b
})
```

## 解决问题

### 共同问题

**1\. 交易模拟失败**

```typescript
// Always simulate transactions before sending
const simResult = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
if (simResult.effects.status.status === 'failure') {
  console.error('Transaction simulation failed:', simResult.effects.status.error)
}
```

**2\. 天然气预算不足**

```typescript
// Set appropriate gas budget for complex operations
tx.setGasBudget(10000000000) // 10 SUI
```

**3\. 活动本位范围验证**

```typescript
// Always check if active bin is within your position range
const amounts_in_active_bin = await sdk.Position.getActiveBinIfInRange(
  pool.bin_manager.bin_manager_handle,
  lower_bin_id,
  upper_bin_id,
  active_id,
  bin_step
)
```

**4\. 价格滑行保护**

```typescript
// Use appropriate slippage protection
const isValid = await sdk.Position.validateActiveIdSlippage({
  pool_id,
  active_id,
  max_bin_slippage: 0.01 // 1% slippage tolerance
})
```

### 调试提示

**1\. 打印交易细节**

```typescript
import { printTransaction } from '@cetusprotocol/common-sdk'

// Print transaction for debugging
printTransaction(tx)
```

**2\. 检查池状态**

```typescript
// Always verify pool state before operations
const pool = await sdk.Pool.getPool(pool_id)
console.log('Pool active_id:', pool.active_id)
console.log('Pool bin_step:', pool.bin_step)
```

**3\. 验证位置数据**

```typescript
// Parse and validate position liquidity shares
const active_bin = await sdk.Pool.getBinInfo(pool.bin_manager.bin_manager_handle, pool.active_id, pool.bin_step)
const liquidity_shares_data = parseLiquidityShares(position.liquidity_shares, pool.bin_step, position.lower_bin_id, active_bin)
console.log('Liquidity shares data:', liquidity_shares_data)
```

## 更多关于 Cetus

使用以下链接来进一步了解 Cetus :

学习更多与Cetus合作 [Cetus 文档](https://cetus-1.gitbook.io/cetus-docs)。 。 。 .

加入Cetus社区 [Cetus 迪斯科尔](https://discord.com/channels/1009749448022315008/1009751382783447072)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @cetusprotocol/dlmm-sdk 是什么？

Cetus dlmm 的 SDK 定义

### 如何安装 @cetusprotocol/dlmm-sdk？

在项目目录运行 npm install @cetusprotocol/dlmm-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：blakejs（\*）、@mysten/sui（\>=2\.28\.0）、@cetusprotocol/common-sdk（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cetusprotocol/dlmm-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cetusprotocol/dlmm-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cetusprotocol/dlmm-sdk 可以商用吗？

@cetusprotocol/dlmm-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cetusprotocol/dlmm-sdk 的下载量有多少？

根据 npm 官方下载统计，@cetusprotocol/dlmm-sdk 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,387 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cetusprotocol/dlmm-sdk 还在维护吗？

最新版本 1\.3\.3 发布于 2026/10/01（1 个月前）；至今共发布 89 个版本，其中过去 12 个月发布了 46 个；首次发布于 2025/09/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。