# @gauntlet-xyz/sdk 中文文档

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

版本：3\.1\.1
npm 元数据更新时间：2026-11-06T18:32:02.287Z
中文译文更新时间：2026-11-16T00:12:16.051Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gauntlet-xyz/sdk
原文对照：https://npmcn.com/package/%40gauntlet-xyz/sdk/?lang=original
项目主页：https://github.com/Gauntlet-xyz/sdk#readme
源码仓库：https://github.com/Gauntlet-xyz/sdk

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

- 包体积（解压后）：3.8 MB，330 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：viem \>=2\.0\.0
- 首次发布：2026-04-17T18:47:51.385Z
- 最新版本发布：2026-11-06T18:32:01.899Z
- 近 30 天下载量：11150（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

官方Gauntlet SDK金库存款、提取和归属

## 安装

```sh
npm install @gauntlet-xyz/sdk
```

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

## README

# @grandlet-xyz/sdk (英语)

官方Gauntlet SDK与Gauntlet管理的金库互动——存款,提款,链上归属,以及Gauntlet REST API(地壳,位置,PnL,活性).

## 文档

完整文档、指南和API参考文献 **[(原始内容存档于2017-10-26) (英语). docs.glantlet.xyz](https://docs.gauntlet.xyz/)**。 。 。 .

## 安装

```bash
npm install @gauntlet-xyz/sdk viem
# or
yarn add @gauntlet-xyz/sdk viem
```

> `viem` 是一个必要的同伴依赖.

## 节点.js

一揽子计划支持无害环境管理 `import` 和通用JS系统 `require` 在节点.js. 两个出入口都使用相同的SDK出口.

```js
import { GauntletClient } from '@gauntlet-xyz/sdk';
```

```js
const { GauntletClient } = require('@gauntlet-xyz/sdk');
```

## 快开始

```ts
import { createPublicClient, createWalletClient, custom, http } from 'viem';
import { base } from 'viem/chains';
import { GauntletClient, getVaults, getDepositTx } from '@gauntlet-xyz/sdk';

const client = new GauntletClient({
  evmClients: { [base.id]: createPublicClient({ chain: base, transport: http() }) },
  wallet: createWalletClient({ chain: base, transport: custom(window.ethereum) }),
  builderCode: 'my-app', // ERC-8021 attribution
});

const vaults = await getVaults(client, { chainId: base.id });
const steps = await getDepositTx(client, { vaultId: vaults[0].vaultId, amount: 100_000_000n });
for (const step of steps) {
  await client.wallet!.sendTransaction({
    to: step.payload.to,
    data: step.payload.data, // attribution suffix already applied
    account: step.payload.account!,
    chain: base,
  });
}
```

使用 [枢密院](https://privy.io/)? 吗? `@gauntlet-xyz/sdk/privy` 在一个呼叫中构建客户端 :

```ts
import { createGauntletClientFromPrivy } from '@gauntlet-xyz/sdk/privy';
import { base } from 'viem/chains';

const client = await createGauntletClientFromPrivy({
  wallet: wallets[0], // from useWallets()
  chains: [base],
  builderCode: 'my-app',
});
```

## Aera 即时存款

引用 Aera V2 即时存款,然后将其最小输出传递给交易构建者.

```ts
import { getDepositTx, getSyncDepositQuote, VaultId } from '@gauntlet-xyz/sdk';

const request = {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
  slippageBps: 100,
};
let quote = await getSyncDepositQuote(client, request);
let steps = await getDepositTx(client, {
  ...request,
  depositMode: 'sync',
  minUnitsOut: quote.minUnitsOut,
});

while (steps[0]?.tx.type === 'approve') {
  await sendAndConfirm(steps[0]);
  quote = await getSyncDepositQuote(client, request);
  steps = await getDepositTx(client, {
    ...request,
    depositMode: 'sync',
    minUnitsOut: quote.minUnitsOut,
  });
}
if (steps[0]?.tx.type !== 'deposit') {
  throw new Error('The transaction builder returned no deposit step.');
}
await sendAndConfirm(steps[0]);
```

`SyncDepositQuote` 有五个需要的领域: `unitsOut`, (中文(简体) ), `minUnitsOut`, (中文(简体) ), `numeraireOut`, (中文(简体) ), `feeBps`,以及 `slippageBps`。 。 。 . `slippageBps` 是用来得出 `minUnitsOut`· ; `feeBps` 实值 (一) 适用于存款代号金额的即时供应费; `numeraireOut` 是收费后的押金 转换为金库数字的金额,用于显示。 合同执行 `minUnitsOut`重新引用 每次批准后,存款签名使用最新审查的最低金额。 有些标志需要 最终批准前为零.

使用 `getSyncDepositRate` 阅读实时即时供应费,不需金额,例如显示费用 用户输入存款金额前的字幕 :

```ts
import { getSyncDepositRate, VaultId } from '@gauntlet-xyz/sdk';

const { feeBps } = await getSyncDepositRate(client, { vaultId: VaultId.AeraUsdAlpha });
```

## Aera 即时撤离

使用实能结果来决定是否提供即时退出,然后通过 引用回 `getWithdrawTx` 因此提交的交易使用引用的界限.

```ts
import {
  getAeraTokenModeSupport,
  getSyncWithdrawQuote,
  getWithdrawTx,
  VaultId,
} from '@gauntlet-xyz/sdk';

const vaultId = VaultId.AeraUsdAlpha;
const support = await getAeraTokenModeSupport(client, { vaultId });

if (support.syncRedeem) {
  const quote = await getSyncWithdrawQuote(client, {
    vaultId,
    amount: 1_000_000n,
    slippageBps: 100,
  });
  const steps = await getWithdrawTx(client, {
    vaultId,
    amount: 1_000_000n,
    syncWithdrawQuote: quote,
  });
}
```

使用 `quote.rate` 与引文相关的区块一致的速率。 只拿活的来 比率 :

```ts
import { getSyncWithdrawRate } from '@gauntlet-xyz/sdk';

const rate = await getSyncWithdrawRate(client, { vaultId });
```

`getSyncWithdrawRate` 接受导出 `SyncWithdrawRateParams` 并返回基地, 动态比价,和有效乘法,不需要金额或账户.

一个 `amount` 引用使用精确的符号输出并返回 a `maxUnitsIn` 约束。 A 类 `shares` 引用使用 准确份额并返回 a `minTokensOut` 约束。 全位置引号需要 `{ entireAmount: true, account }`;匹配交易使用已配置的钱包账户, 和可选 `account` 必须匹配钱包。 回来的 `SyncWithdrawQuote` 直接为 可转让导出 `SyncWithdrawQuoteBounds` 已经接受 `getWithdrawTx`。Redeem 引用 还包括: `shareSafeTokensOut`最大准确的退出 保存了滑坡 引用的股份里的房间. `capacity.knownLiquidityTokens` 报告金库的代币 只有在没有拉出资金的调取数据时,才能产生更多的流动资金;否则就没有定义.

供应 `syncWithdrawQuote` 表示同步模式并验证其金库,链条,令牌,账户, 滑行,和大小请求。 当交易滑行被省略时,构建者使用引用 出错; 明确提供的值必须匹配 。 A 类 `shares` 或者说 `entireAmount` 引用为 `slippageBps: 10000` 因为它会产生 `minTokensOut: 0`。 。 。 .

现场能力检查也应用了V2解析门. 当门暂停提供/托肯时 ,两个同步标记都是虚假的,同步引号或交易请求被拒绝.

常见的失败是 `UnsupportedDepositModeError`, (中文(简体) ), `UnsupportedFeatureError`, (中文(简体) ), `StalePriceError`, (中文(简体) ), `InvalidSyncWithdrawBoundError`, (中文(简体) ), `InvalidWithdrawParamsError`, (中文(简体) ), `AccountRequiredError`,以及 `AccountMismatchError`。 。 。 .

## REST API (英语:`client.api`(中文(简体) )

`client.api` 是Gauntlet API 的已输入客户端 `api.gauntlet.xyz` ——有索引的金库度量衡,有PnL的用户位置,钱包活性日志,TVL,和象征性价格. 反应类型由服务OpenAPI spec生成,并在CI中被验证,因此无法漂移.

```ts
const client = new GauntletClient({ apiKey: process.env.GAUNTLET_API_KEY });

const { data: vaults } = await client.api.vaults(); // live TVL / APY / unit price
const { data: positions } = await client.api.positions(wallet); // value, cost basis, PnL, ROI
const { data: history } = await client.api.positionTimeseries(wallet, vaultId);
const { data: vaultHistory } = await client.api.vaultTimeseriesBySlug('gtusda'); // aggregate TVL + primary metrics
const { data: primary } = await client.api.primaryVaultTimeseriesBySlug('gtusda'); // primary only
```

对逻辑错误历史, 使用 `vaultTimeseriesBySlug`: 每个点包含 合计 `tvl.usd` 财务报告和审定财务报表 `total_supply` 连同初级部署 `apy_7d`, (中文(简体) ), `apy_30d`, (中文(简体) ), `apy_90d`,以及 `unit_price`。 。 。 . `meta.resolved_vault_id` 识别这个初级. 数值为缺失数据,应作为空白。 使用 `primaryVaultTimeseriesBySlug` 当所有衡量标准,包括TVL,应当描述 仅是主要部署;这种反应还包括其原生TVL.

API上的断层识别码是 CAIP-10(`"{chainId}:{address}"`; 转换为或从显示的金库编号 `apiVaultIdFromVaultId` 编号 : `vaultIdFromApiVaultId`。货币值为人单位小数字符串;与 `decimalToBigInt` 编号 : `sharesToBigInt` (掷出而去取取相.

### 交易和平衡安全

准备的交易包括: `chainId` 两者 `payload` 财务报告和审定财务报表 `tx`。 。 。 . 在签署每个步骤前检查账户和链条. 在钱包账户或链条更改后重建步骤 .

关于从下列来源提取的准确款项: `shareSafeTokensOut`,通过 `maxShares: quote.shares` 改为 `getWithdrawTx`。 。 。 . 这一上限在费率变动后仍然有效. 合同拒绝需要更多股份的提款.

`getUserCurrentBalance` 读取平衡、转换和请求状态. 它过滤选中的符号待处理的请求 . 多资产部署需要 `assetSymbol`,作为 `getDepositTx` 已经. 默认扫描覆盖所配置的请求寿命,最少3天. 使用 `fromBlock` 包括更早的请求,包括仍然持有代管权的过期请求. 设有若干部署的金库也需要 `chainId` 与 `fromBlock`。 。 。 . 每项结果包括: `blockNumber` 财务报告和审定财务报表 `fromBlock` 以确定其范围. `pendingWithdraw` 报告代管股票的现值毛额. 它不承诺在乘数或解答者提示后支付结算.

### 活动流动

`getActivityFlows` 将原始活性日志接入生命周期认知流 – Aera async 请求与它们的结算或退款组合通过 `request_hash`,替换客户端事件日志扫描 :

```ts
import { getActivityFlows, waitForRequestSettlement } from '@gauntlet-xyz/sdk';

const flows = await getActivityFlows(client.api, wallet);
// [{ kind: 'deposit', status: 'pending', requestedAt, settledAt, assets, shares, txHashes, ... }]

// After submitting a requestDeposit / requestRedeem transaction:
const settled = await waitForRequestSettlement(client.api, wallet, requestHash, { requestTxHash });
```

定居投票要求 `requestTxHash`,所提交请求的散列交易. 这使得新的请求与先前提出的相关散列请求相分离. 活动帮助者拒绝不完整的页面,行出时间戳顺序,重复光标,以及无效的生命周期三角洲. 行不包含事件索引,所以在一个交易中相同的行会保持单独的行. 立场历史拒绝混合资产面额和无比代管. API客户端拒绝重定向以防止证书转发.

### 位置历史

`getPositionHistory` 将钱包的索引事件重放为时间顺序定位时间表——运行股权余额,代管待付金额和净资产流量:

```ts
import { getPositionHistory, apiVaultIdFromVaultId } from '@gauntlet-xyz/sdk';

const vaultId = await apiVaultIdFromVaultId(client, 'gtusda');
const { points } = await getPositionHistory(client.api, wallet, vaultId);
```

## 收费包装金库(伙伴)

合伙人收费保险箱是专门为一个合伙人部署的Aera保险箱,因此不在捆绑的货单上。 登记您的 `client.setManifest`: 扩展 `await client.manifest` 包含您的金库条目( Gauntlet 提供的部署值), 然后每个 SDK 函数接受其 `vaultId`见 [收费包装指南](https://docs.gauntlet.xyz/sdk/reference#fee-wrapper-vaults-partners) 举个例子.

## 发展

`src/api/generated.ts` 从 `services/gaia/api/openapi.json` - 与 `yarn generate:api-types` aPI 修改后; CI 如果漂移则失败 .

## 常见问题

### @gauntlet-xyz/sdk 是什么？

官方Gauntlet SDK金库存款、提取和归属

### 如何安装 @gauntlet-xyz/sdk？

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

### @gauntlet-xyz/sdk 支持 TypeScript 吗？

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

### @gauntlet-xyz/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gauntlet-xyz/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gauntlet-xyz/sdk 可以商用吗？

@gauntlet-xyz/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gauntlet-xyz/sdk 的下载量有多少？

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

### @gauntlet-xyz/sdk 还在维护吗？

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

