# @balmy/sdk 中文文档

规范地址：https://npmcn.com/package/%40balmy/sdk/

版本：0\.9\.0
npm 元数据更新时间：2025-05-19T17:48:07.088Z
中文译文更新时间：2026-11-07T15:51:50.635Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：1.5 MB，575 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2024-04-26T20:54:44.809Z
- 最新版本发布：2025-05-19T17:48:06.897Z
- 近 30 天下载量：10401（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：87（近 12 个月 0 个）

## 中文简介

一个全面的TypeScript SDK,用于与Balmy协议和各种块链网络互动.

## 安装

```sh
npm install @balmy/sdk
```

也可以使用：`pnpm add @balmy/sdk`、`yarn add @balmy/sdk`、`bun add @balmy/sdk`

## README

# 鲍米SDK

一个全面的TypeScript SDK,用于与Balmy协议和各种块链网络互动.

## \* 安装

### 雅伦

```bash
yarn add @balmy/sdk
```

### 国家预防机制

```bash
npm install @balmy/sdk
```

## 快速启动

### 建设SDK

```typescript
import { buildSDK } from "@balmy/sdk";

const sdk = buildSDK(config);
```

### QQ 为多键获取平衡

```typescript
const accountBalances = await sdk.balanceService.getBalancesForTokens({
  account: "0x000000000000000000000000000000000000dead",
  tokens: {
    [Chains.ETHEREUM.chainId]: [
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
      "0x6b175474e89094c44da98b954eedeac495271d0f", // DAI
    ],
    [Chains.OPTIMISM.chainId]: [
      "0x7f5c764cbc14f9669b88837ca1490cca17c31607", // USDC
      "0xda10009cbd5d07dd0cecc66161fc93d7c9000da1", // DAI
    ],
  },
  config: {
    timeout: "30s",
  },
});
```

### 获得津贴

```typescript
const accountAllowances = await sdk.allowanceService.getAllowances({
  chainId: Chains.ETHEREUM.chainId,
  token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
  owner: "0x000000000000000000000000000000000000dead",
  spenders: ["0x6666666600000000000000000000000000009999"],
});
```

### QQ 获得贸易引文

```typescript
const allQuotes = await sdk.quoteService.getAllQuotesWithTxs({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    buyToken: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    order: {
      type: "sell",
      sellAmount: utils.parseUnits("1000", 6), // 1000 USDC
    },
    slippagePercentage: 1,
    takerAddress: signer.address,
    gasSpeed: {
      speed: "instant",
    },
  },
  config: {
    sort: {
      by: "most-swapped-accounting-for-gas",
    },
  },
});
```

## 概览

Balmy SDK是一个综合性TypeScript库,为与Balmy协议和各种块链网络的互动提供统一的接口. Balmy SDK 允许您与 Balmy 协议交互, 提供高效的工具来管理符号余额, 从 DEX 聚合器取回交易报价, 并检查符号持有量跨多条链 。 它的设计是模块化的,每个功能都组织为专门服务,处理区块链相互作用的特定方面.

### 可用服务

SDK分为:

-   **[津贴处](https://npmcn.com/package/%40balmy/sdk/#readme-allowances-service)**: 管理不同链条的令牌批准和权限
-   **[余额处](https://npmcn.com/package/%40balmy/sdk/#readme-balances-service)**: 查询多个链条和符号之间的符号平衡
-   **[引用服务](https://npmcn.com/package/%40balmy/sdk/#readme-quotes-service)**: 从各种 DEX 聚合器获取优化的交换报价
-   **[天然气服务](https://npmcn.com/package/%40balmy/sdk/#readme-gas-service)**:优化交易成本并估算天然气价格
-   **[价格处](https://npmcn.com/package/%40balmy/sdk/#readme-prices-service)**: 获取跨越多个链条的象征性价格信息
-   **[元数据服务](https://npmcn.com/package/%40balmy/sdk/#readme-metadata-service)**: 获取令牌元数据和信息
-   **[许可服务2](https://npmcn.com/package/%40balmy/sdk/#readme-permit2-service)**: 使用许可2 协议管理令牌批准
-   **[DCA服务](https://npmcn.com/package/%40balmy/sdk/#readme-dca-service)**: 设立并管理美元成本分析职位
-   **[收入服务](https://npmcn.com/package/%40balmy/sdk/#readme-earn-service)**: 处理生产性耕作作业

每项服务提供一组重点功能,同时保持一致的接口和出错处理方法. 这种模块化设计允许开发人员只使用他们所需要的服务,同时确保整个SDK的一致经验.

## 服务

### 津贴处

津贴处提供各种功能,检查和管理不同环节的象征性津贴.

#### 目标和潜力

-   **目标**: 实现跨多条链和协议的代号审批的有效管理
-   **潜在用途案例**数字 :
    -   批量检查一次呼叫中的多个符号批准
    -   通过交易前检查批准情况来优化天然气成本
    -   管理 DeFi 协议和 dApps 的权限
    -   跨链津贴监测和管理

#### 方法

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.allowanceService.supportedChains();
```

##### `getAllowanceInChain(params)`

获得特定代币和特定链上花花子的补贴.

```typescript
const allowance = await sdk.allowanceService.getAllowanceInChain({
  chainId: Chains.ETHEREUM.chainId,
  token: "0x...", // Token address
  owner: "0x...", // Owner address
  spender: "0x...", // Spender address
  config: { timeout: TimeString },
});
```

##### `getAllowancesInChain(params)`

在一次征召中获得特定链条的多份津贴.

```typescript
const allowances = await sdk.allowanceService.getAllowancesInChain({
  chainId: Chains.ETHEREUM.chainId,
  allowances: [
    { token: "0x...", owner: "0x...", spender: "0x..." },
    { token: "0x...", owner: "0x...", spender: "0x..." },
  ],
  config: { timeout: TimeString },
});
```

##### `getAllowances(params)`

在一次呼叫中获得跨多条链的津贴.

```typescript
const allowances = await sdk.allowanceService.getAllowances({
  allowances: [
    {
      chainId: Chains.ETHEREUM.chainId,
      token: "0x...",
      owner: "0x...",
      spender: "0x...",
    },
    {
      chainId: Chains.OPTIMISM.chainId,
      token: "0x...",
      owner: "0x...",
      spender: "0x...",
    },
  ],
  config: { timeout: TimeString },
});
```

### 余额处

平衡服务允许在多条链条和道具之间查询符号平衡.

#### 目标和潜力

-   **目标**: 提供一个统一的接口,用于在多条链条之间检索符号余额
-   **潜在用途案例**数字 :
    -   跨多个链的组合跟踪
    -   DeFi 位置的余额监测
    -   多链钱包集成
    -   贸易战略自动平衡检查

#### 方法

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.balanceService.supportedChains();
```

##### `getBalancesForAccountInChain(params)`

获取单一链中特定账户的余额.

```typescript
const balances = await sdk.balanceService.getBalancesForAccountInChain({
  chainId: Chains.ETHEREUM.chainId,
  account: "0x...",
  tokens: ["0x...", "0x..."],
  config: { timeout: "30s" },
});
```

##### `getBalancesForAccount(params)`

通过多个链获取特定账户的余额.

```typescript
const balances = await sdk.balanceService.getBalancesForAccount({
  account: "0x...",
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
  ],
  config: { timeout: "30s" },
});
```

##### `getBalancesInChain(params)`

在单一链中获取多个账户的余额.

```typescript
const balances = await sdk.balanceService.getBalancesInChain({
  chainId: Chains.ETHEREUM.chainId,
  tokens: [
    { account: "0x...", token: "0x..." },
    { account: "0x...", token: "0x..." },
  ],
  config: { timeout: "30s" },
});
```

##### `getBalances(params)`

获取多个连锁账户的余额.

```typescript
const balances = await sdk.balanceService.getBalances({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, account: "0x...", token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, account: "0x...", token: "0x..." },
  ],
  config: { timeout: "30s" },
});
```

### 引用服务

引用服务为从各种DEX聚合器获取交易报价提供了全面的功能.

#### 目标和潜力

-   **目标**: 汇总并优化来自多个DEX来源的贸易报价
-   **潜在用途案例**数字 :
    -   寻找跨越多个DEX的最佳贸易路线
    -   天然气最佳贸易战略
    -   跨链套利机会
    -   自动交易系统
    -   价格影响分析

#### 方法

##### `supportedSources()`

返回所有被支持的引用源的元数据 .

```typescript
const sources = sdk.quoteService.supportedSources();
```

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.quoteService.supportedChains();
```

##### `supportedSourcesInChain(params)`

返回关于特定链条中支持的引用源的元数据.

```typescript
const sources = sdk.quoteService.supportedSourcesInChain({
  chainId: Chains.ETHEREUM.chainId,
});
```

##### `supportedGasSpeeds()`

返回每个链条所支持的气体速度.

```typescript
const gasSpeeds = sdk.quoteService.supportedGasSpeeds();
```

##### `estimateQuotes(params)`

获得所有来源的估计引用,而不提供交易细节.

```typescript
const quotes = sdk.quoteService.estimateQuotes({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
  },
  config: { timeout: TimeString },
});
```

##### `estimateAllQuotes(params)`

获得所有来源的估计引用,然后在排序的数组中返回 .

```typescript
const quotes = await sdk.quoteService.estimateAllQuotes({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
  },
  config: {
    ignoredFailed: boolean,
    sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
    timeout: TimeString,
  },
});
```

##### `getQuotes(params)`

获得来自所有来源的带有交易细节的引用.

```typescript
const quotes = sdk.quoteService.getQuotes({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
    takerAddress: "0x...",
  },
  config: { timeout: TimeString },
});
```

##### `getAllQuotes(params)`

获得所有来源的引用,然后在排序的数组中返回.

```typescript
const quotes = await sdk.quoteService.getAllQuotes({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
    takerAddress: "0x...",
  },
  config: {
    ignoredFailed: boolean,
    sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
    timeout: TimeString,
  },
});
```

##### `getBestQuote(params)`

根据指定标准获得最佳报价.

```typescript
const bestQuote = await sdk.quoteService.getBestQuote({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
    takerAddress: "0x...",
  },
  config: {
    choose: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
    timeout: TimeString,
  },
});
```

##### `getAllQuotesWithTxs(params)`

以所有来源的已建交易来引用 .

```typescript
const quotesWithTxs = await sdk.quoteService.getAllQuotesWithTxs({
  request: {
    chainId: Chains.ETHEREUM.chainId,
    sellToken: "0x...",
    buyToken: "0x...",
    order: { type: "sell", sellAmount: BigInt("1000000") },
    slippagePercentage: 1,
    takerAddress: "0x...",
  },
  config: {
    ignoredFailed: boolean,
    sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
    timeout: TimeString,
  },
});
```

##### `buildTxs(params)`

构建给定引用的交易.

```typescript
const txs = sdk.quoteService.buildTxs({
  quotes: quotes,
  sourceConfig: SourceConfig,
  config: { timeout: TimeString },
});
```

##### `buildAllTxs(params)`

构建所有引用的交易,并在排序的数组中返回.

```typescript
const allTxs = await sdk.quoteService.buildAllTxs({
  quotes: quotes,
  sourceConfig: SourceConfig,
  config: {
    timeout: TimeString,
    ignoredFailed: boolean,
  },
});
```

### DCA服务

DCA(Dollar Cost Averaging)服务提供设置和管理DCA职位的功能.

#### 目标和潜力

-   **目标**: 启用任何对符的自动美元成本平均策略
-   **潜在用途案例**数字 :
    -   自动化投资战略
    -   通过定期投资进行风险管理
    -   自定义 DCA 调度
    -   多链DCA职位
    -   共享职位的许可管理

#### 方法

##### `getAllowanceTarget(params)`

获取DCA职位的备抵目标地址.

```typescript
const target = sdk.dcaService.getAllowanceTarget({
  chainId: Chains.ETHEREUM.chainId,
  from: "0x...", // Token to sell
  depositWith: "0x...", // Token to deposit with
  usePermit2: boolean,
});
```

##### `preparePermitData(params)`

准备允许批准文件的数据.

```typescript
const permitData = await sdk.dcaService.preparePermitData({
  // Permit2 parameters
});
```

##### `buildCreatePositionTx(params)`

构建交易以创建新的 DCA 位置.

```typescript
const tx = await sdk.dcaService.buildCreatePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  from: { address: "0x...", variantId: "..." },
  to: { address: "0x...", variantId: "..." },
  swapInterval: DCASwapInterval.ONE_DAY,
  amountOfSwaps: 30,
  owner: "0x...",
  permissions: [{ operator: "0x...", permissions: [DCAPermission.INCREASE] }],
  deposit: { token: "0x...", amount: BigInt("1000000") },
});
```

##### `buildIncreasePositionTx(params)`

构建交易以增加现有的DCA位置.

```typescript
const tx = await sdk.dcaService.buildIncreasePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "123",
  increase: { token: "0x...", amount: BigInt("1000000") },
  amountOfSwaps: 30,
});
```

##### `buildReducePositionTx(params)`

构建交易以减少现有的DCA位置.

```typescript
const tx = await sdk.dcaService.buildReducePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "123",
  amountOfSwaps: 15,
  reduce: { amount: BigInt("500000") },
  recipient: "0x...",
});
```

##### `buildReduceToBuyPositionTx(params)`

构建交易以减少购买特定金额的位置.

```typescript
const tx = await sdk.dcaService.buildReduceToBuyPositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "123",
  amountOfSwaps: 15,
  reduce: { amountToBuy: BigInt("500000") },
  recipient: "0x...",
});
```

##### `buildWithdrawPositionTx(params)`

构建交易以退出 DCA 位置.

```typescript
const tx = await sdk.dcaService.buildWithdrawPositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "123",
  withdraw: {},
  recipient: "0x...",
});
```

##### `buildTerminatePositionTx(params)`

构建交易以终止 DCA 位置.

```typescript
const tx = await sdk.dcaService.buildTerminatePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "123",
  withdraw: {},
  recipient: "0x...",
});
```

##### `buildMigratePositionTx(params)`

构建交易以将 DCA 位置迁移到新中心 .

```typescript
const tx = await sdk.dcaService.buildMigratePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  sourceHub: "0x...",
  targetHub: "0x...",
  positionId: "123",
  migration: { useFundsFrom: "swapped", sendUnusedFundsTo: "0x..." },
});
```

##### `getSupportedPairs(params)`

DCA 位置获得支持的令牌对 .

```typescript
const pairs = await sdk.dcaService.getSupportedPairs({
  chains: [Chains.ETHEREUM.chainId],
  config: { timeout: "30s" },
});
```

##### `getPositionsByAccount(params)`

获取 DCA 特定账户的位置 .

```typescript
const positions = await sdk.dcaService.getPositionsByAccount({
  accounts: ["0x..."],
  chains: [Chains.ETHEREUM.chainId],
  includeHistory: true,
  config: { timeout: "30s" },
});
```

##### `getPositionsById(params)`

通过他们的身份证获取DCA的位置.

```typescript
const positions = await sdk.dcaService.getPositionsById({
  ids: [{ chainId: Chains.ETHEREUM.chainId, hub: "0x...", positionId: 123 }],
  includeHistory: true,
  config: { timeout: "30s" },
});
```

##### `getPairSwaps(params)`

将历史换成一对标志.

```typescript
const swaps = await sdk.dcaService.getPairSwaps({
  chainId: Chains.ETHEREUM.chainId,
  variantTokenA: "...",
  variantTokenB: "...",
  config: { timeout: "30s" },
});
```

### 天然气服务

天然气服务提供不同链条的天然气价格估计和优化.

#### 目标和潜力

-   **目标**:优化不同链条和网络的交易成本
-   **潜在用途案例**数字 :
    -   天然气价格监测和优化
    -   交易费用估计数
    -   天然气认识贸易战略
    -   多链天然气价格比较
    -   天然气价格自动优化

#### 方法

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.gasService.supportedChains();
```

##### `supportedSpeeds()`

返回每个链条所支持的气体速度.

```typescript
const speeds = sdk.gasService.supportedSpeeds();
```

##### `estimateGas(params)`

估计交易的气体用量.

```typescript
const gasEstimation = await sdk.gasService.estimateGas({
  chainId: Chains.ETHEREUM.chainId,
  tx: {
    from: "0x...",
    to: "0x...",
    data: "0x...",
  },
  config: { timeout: TimeString },
});
```

##### `getGasPrice(params)`

在链上获得不同速度的天然气价格.

```typescript
const gasPrices = await sdk.gasService.getGasPrice({
  chainId: Chains.ETHEREUM.chainId,
  config: {
    timeout: TimeString,
    fields: {
      standard: "required" | "best effort" | "can ignore",
      fast: "required" | "best effort" | "can ignore",
      instant: "required" | "best effort" | "can ignore",
    },
  },
});
```

##### `calculateGasCost(params)`

计算交易的天然气成本.

```typescript
const gasCost = await sdk.gasService.calculateGasCost({
  chainId: Chains.ETHEREUM.chainId,
  gasEstimation: BigInt("21000"),
  tx: {
    from: "0x...",
    to: "0x...",
    data: "0x...",
  },
  config: {
    timeout: TimeString,
    fields: {
      standard: "required" | "best effort" | "can ignore",
      fast: "required" | "best effort" | "can ignore",
      instant: "required" | "best effort" | "can ignore",
    },
  },
});
```

##### `getQuickGasCalculator(params)`

获得特定链的快速气体计算器.

```typescript
const calculator = await sdk.gasService.getQuickGasCalculator({
  chainId: Chains.ETHEREUM.chainId,
  config: {
    timeout: TimeString,
    fields: {
      standard: "required" | "best effort" | "can ignore",
      fast: "required" | "best effort" | "can ignore",
      instant: "required" | "best effort" | "can ignore",
    },
  },
});

// Use the calculator
const gasPrices = calculator.getGasPrice();
const gasCost = calculator.calculateGasCost({
  gasEstimation: BigInt("21000"),
  tx: {
    from: "0x...",
    to: "0x...",
    data: "0x...",
  },
});
```

### 价格处

物价服务提供跨越多条链条的象征性价格信息.

#### 目标和潜力

-   **目标**: 提供一个统一的接口, 用于在多条链条中检索象征性价格
-   **潜在用途案例**数字 :
    -   DeFi 应用程序的价格种子
    -   调值计算
    -   历史价格分析
    -   价格图生成
    -   多链价格汇总

#### 方法

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.pricesService.supportedChains();
```

##### `supportedQueries()`

返回每个链条支持的价格查询.

```typescript
const queries = sdk.pricesService.supportedQueries();
```

##### `getCurrentPricesInChain(params)`

在特定链条中获取令牌的当前价格.

```typescript
const prices = await sdk.pricesService.getCurrentPricesInChain({
  chainId: Chains.ETHEREUM.chainId,
  tokens: ["0x...", "0x..."],
  config: { timeout: "30s" },
});
```

##### `getCurrentPrices(params)`

获得跨多条链的代币的时价.

```typescript
const prices = await sdk.pricesService.getCurrentPrices({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
  ],
  config: { timeout: "30s" },
});
```

##### `getHistoricalPricesInChain(params)`

在特定时间戳中获取特定链条中标志的历史价格.

```typescript
const prices = await sdk.pricesService.getHistoricalPricesInChain({
  chainId: Chains.ETHEREUM.chainId,
  tokens: ["0x...", "0x..."],
  timestamp: 1234567890,
  searchWidth: "1h",
  config: { timeout: "30s" },
});
```

##### `getHistoricalPrices(params)`

在一个特定的时间戳上获得跨多条链条的令牌的历史价格.

```typescript
const prices = await sdk.pricesService.getHistoricalPrices({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
  ],
  timestamp: 1234567890,
  searchWidth: "1h",
  config: { timeout: "30s" },
});
```

##### `getBulkHistoricalPrices(params)`

以不同的时间戳获得多个符牌的历史价格.

```typescript
const prices = await sdk.pricesService.getBulkHistoricalPrices({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x...", timestamp: 1234567890 },
    { chainId: Chains.OPTIMISM.chainId, token: "0x...", timestamp: 1234567890 },
  ],
  searchWidth: "1h",
  config: { timeout: "30s" },
});
```

##### `getChart(params)`

获取特定时间段内令牌的价格图表数据.

```typescript
const chart = await sdk.pricesService.getChart({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
  ],
  span: 100,
  period: "1d",
  bound: { from: 1234567890 },
  searchWidth: "1h",
});
```

### 元数据服务

元数据服务提供跨越多个链条的象征性元数据信息.

#### 目标和潜力

-   **目标**: 提供一个统一接口,用于在多个链条中检索符名元数据
-   **潜在用途案例**数字 :
    -   在 UIs 中隐藏信息
    -   Token 验证和核查
    -   多链令牌管理
    -   输入数据汇总

#### 方法

##### `supportedChains()`

返回服务支持的链式ID.

```typescript
const chains = sdk.metadataService.supportedChains();
```

##### `supportedProperties()`

返回每个链条所支持的元数据属性.

```typescript
const properties = sdk.metadataService.supportedProperties();
```

##### `getMetadataInChain(params)`

获取特定链条中符的元数据 .

```typescript
const metadata = await sdk.metadataService.getMetadataInChain({
  chainId: Chains.ETHEREUM.chainId,
  tokens: ["0x...", "0x..."],
  config: {
    fields: { symbol: "required", decimals: "required" },
    timeout: "30s",
  },
});
```

##### `getMetadata(params)`

获得跨越多条链的符号元数据 .

```typescript
const metadata = await sdk.metadataService.getMetadata({
  tokens: [
    { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
    { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
  ],
  config: {
    fields: { symbol: "required", decimals: "required" },
    timeout: "30s",
  },
});
```

### 许可服务2

许可证2处提供功能,使用许可证2协议管理批准令.

#### 目标和潜力

-   **目标**: 启用使用许可证2标准的高效和安全的令牌批准
-   **潜在用途案例**数字 :
    -   天然气最佳代号批准
    -   批次核准
    -   跨议定书许可管理
    -   自动核准系统
    -   注重安保的核准工作流程

```typescript
// Get permit2 allowance
const allowance = await sdk.permit2Service.getAllowance({
  chainId: Chains.ETHEREUM.chainId,
  token: "0x...",
  owner: "0x...",
  spender: "0x...",
});
```

### 收入服务

收入服务为生产性耕作和打捞业务提供功能.

#### 目标和潜力

-   **目标**: 允许在多个协议之间开展高效的生产性耕作和采集作业
-   **潜在用途案例**数字 :
    -   义德农业战略管理
    -   职位自动化管理
    -   跨议定书产量优化
    -   以许可为基础的职位共享
    -   延迟撤离管理
    -   战略迁移和优化

#### 方法

##### `getAllowanceTarget(params)`

获取策略的津贴目标地址.

```typescript
const target = await sdk.earnService.getAllowanceTarget({
  chainId: Chains.ETHEREUM.chainId,
  strategyId: "1-0x1234567890123456789012345678901234567890-42", // Format: chainId-registryAddress-strategyNumber
  depositWith: "0x...", // Token to deposit with
  usePermit2: boolean,
});
```

##### `preparePermitData(params)`

准备允许批准文件的数据.

```typescript
const permitData = await sdk.earnService.preparePermitData({
  chainId: Chains.ETHEREUM.chainId,
  token: "0x...",
  amount: "1000000",
  spender: "0x...",
});
```

##### `preparePermissionData(params)`

为职位管理准备许可数据.

```typescript
const permissionData = await sdk.earnService.preparePermissionData({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "1-0xabcdef1234567890123456789012345678901234-1337", // Format: chainId-vaultAddress-positionNumber
  permissions: [{ operator: "0x...", permissions: [EarnPermission.INCREASE] }],
  signerAddress: "0x...",
  signatureValidFor: "1w",
});
```

##### `buildCreatePositionTx(params)`

构建交易以创建新的挣取位置.

```typescript
const tx = await sdk.earnService.buildCreatePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  strategyId: "1-0x1234567890123456789012345678901234567890-42", // Format: chainId-registryAddress-strategyNumber
  owner: "0x...",
  permissions: [{ operator: "0x...", permissions: [EarnPermission.INCREASE] }],
  deposit: { token: "0x...", amount: "1000000" },
});
```

##### `buildIncreasePositionTx(params)`

构建交易以增加现有位置.

```typescript
const tx = await sdk.earnService.buildIncreasePositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "1-0xabcdef1234567890123456789012345678901234-1337", // Format: chainId-vaultAddress-positionNumber
  increase: { token: "0x...", amount: "1000000" },
});
```

##### `buildWithdrawPositionTx(params)`

构建交易以退出一个位置.

```typescript
const tx = await sdk.earnService.buildWithdrawPositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "1-0xabcdef1234567890123456789012345678901234-1337", // Format: chainId-vaultAddress-positionNumber
  withdraw: { type: "market", token: "0x...", amount: "1000000" },
});
```

##### `buildClaimDelayedWithdrawPositionTx(params)`

构建交易以要求延迟退出.

```typescript
const tx = await sdk.earnService.buildClaimDelayedWithdrawPositionTx({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "1-0xabcdef1234567890123456789012345678901234-1337", // Format: chainId-vaultAddress-positionNumber
});
```

##### `estimateMarketWithdraw(params)`

估计从市场退出中将获得的代币数额.

```typescript
const estimation = await sdk.earnService.estimateMarketWithdraw({
  chainId: Chains.ETHEREUM.chainId,
  positionId: "1-0xabcdef1234567890123456789012345678901234-1337", // Format: chainId-vaultAddress-positionNumber
  token: "0x...",
  amount: "1000000",
  swapConfig: {
    slippagePercentage: 1,
    txValidFor: "1w",
  },
});
```

##### `getSupportedStrategies(params)`

获得支持的产量农业战略.

```typescript
const strategies = await sdk.earnService.getSupportedStrategies({
  chains: [Chains.ETHEREUM.chainId],
  config: { timeout: "30s" },
});
```

##### `getStrategy(params)`

获得具体策略的详细信息.

```typescript
const strategy = await sdk.earnService.getStrategy({
  strategy: "1-0x1234567890123456789012345678901234567890-42", // Format: chainId-registryAddress-strategyNumber
  config: { timeout: "30s" },
});
```

##### `getPositionsByAccount(params)`

获得特定账户的职位.

```typescript
const positions = await sdk.earnService.getPositionsByAccount({
  accounts: ["0x..."],
  chains: [Chains.ETHEREUM.chainId],
  includeHistory: true,
  includeHistoricalBalancesFrom: 1672531200,
  config: { timeout: "30s" },
});
```

##### `getPositionsById(params)`

凭他们的身份证获得职位.

```typescript
const positions = await sdk.earnService.getPositionsById({
  ids: ["1-0xabcdef1234567890123456789012345678901234-1337"], // Format: chainId-vaultAddress-positionNumber
  includeHistory: true,
  includeHistoricalBalancesFrom: 1672531200,
  config: { timeout: "30s" },
});
```

##### `getStrategyAsset(params)`

获取策略或位置的资产符 .

```typescript
const asset = await sdk.earnService.getStrategyAsset({
  chainId: Chains.ETHEREUM.chainId,
  strategyId: "1-0x1234567890123456789012345678901234567890-42", // Format: chainId-registryAddress-strategyNumber
  // or positionId: "1-0xabcdef1234567890123456789012345678901234-1337" // Format: chainId-vaultAddress-positionNumber
});
```

## 高级使用

### 处理错误

SDK为所有服务提供全面的错误处理:

```typescript
try {
  const quotes = await sdk.quoteService.getAllQuotes({...});
} catch (error) {
  if (error instanceof FailedToGenerateAnyQuotesError) {
    // Handle quote generation failure
  }
}
```

### 配置

每个服务可以配置自定义超时和其他参数:

```typescript
const quotes = await sdk.quoteService.getAllQuotes({
  request: {...},
  config: {
    timeout: "30s",
    ignoredFailed: true,
    sort: {
      by: "most-swapped-accounting-for-gas",
      using: "gas-price"
    }
  }
});
```

### 多链支持

跨多个链条的所有服务支助业务:

```typescript
const balances = await sdk.balanceService.getBalancesForTokens({
  account: "0x...",
  tokens: {
    [Chains.ETHEREUM.chainId]: ["0x..."],
    [Chains.OPTIMISM.chainId]: ["0x..."],
    [Chains.ARBITRUM.chainId]: ["0x..."],
  },
});
```

## 发展

### 环境设置

```bash
yarn install
```

## 捐款

欢迎捐款! 请随意提交拉力请求.

### [文档](https://docs.balmy.xyz/) | [页:1](https://x.com/balmy_xyz) | [解析器](http://discord.balmy.xyz/)

## 常见问题

### @balmy/sdk 是什么？

一个全面的TypeScript SDK,用于与Balmy协议和各种块链网络互动\.

### 如何安装 @balmy/sdk？

在项目目录运行 npm install @balmy/sdk，或使用 pnpm add / yarn add / bun add。

### @balmy/sdk 支持 TypeScript 吗？

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

### @balmy/sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @balmy/sdk 可以商用吗？

@balmy/sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @balmy/sdk 的下载量有多少？

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

### @balmy/sdk 还在维护吗？

最新版本 0\.9\.0 发布于 2025/05/20（1\.5 年前）；至今共发布 87 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。