@gauntlet-xyz/sdk

中文文档
3.1.1发布于 2026/11/07MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.1万

Official Gauntlet SDK for vault deposits, withdrawals, and attribution

原始使用文档
文档目录12 节
  1. Documentation
  2. Installation
  3. Node.js
  4. Quick start
  5. Aera instant deposits
  6. Aera instant withdrawals
  7. REST API ( client.api )
  8. Transaction and balance safety
  9. Activity flows
  10. Position history
  11. Fee wrapper vaults (partners)
  12. Development

@gauntlet-xyz/sdk

Official Gauntlet SDK for interacting with Gauntlet-managed vaults — deposits, withdrawals, on-chain attribution, and the Gauntlet REST API (vaults, positions, PnL, activity).

Documentation

Full documentation, guides, and API reference at docs.gauntlet.xyz.

Installation

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

viem is a required peer dependency.

Node.js

The package supports ESM import and CommonJS require in Node.js. Both entry points use the same SDK exports.

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

Quick start

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,
  });
}

Using Privy? @gauntlet-xyz/sdk/privy builds the client in one call:

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 instant deposits

Quote an Aera V2 instant deposit, then pass its minimum output to the transaction builder.

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 has five required fields: unitsOut, minUnitsOut, numeraireOut, feeBps, and slippageBps. slippageBps is the basis-point tolerance used to derive minUnitsOut; feeBps is the Instant Supply fee applied to the deposited token amount; numeraireOut is the post-fee deposit amount converted to the vault's numeraire, for display. The contract enforces minUnitsOut. Requote after each approval so the deposit signature uses the latest reviewed minimum. Some tokens require an approval of zero before the final approval.

Use getSyncDepositRate to read the live Instant Supply fee without an amount, e.g. to show a fee caption before the user has typed a deposit amount:

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

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

Aera instant withdrawals

Use the live capability result to decide whether to offer an instant withdrawal, then pass the quote back to getWithdrawTx so the submitted transaction uses the quoted bounds.

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,
  });
}

Use quote.rate for the block-consistent rate associated with the quote. To fetch only the live rate:

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

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

getSyncWithdrawRate accepts the exported SyncWithdrawRateParams and returns the live base, dynamic-premium, and effective multipliers without requiring an amount or account.

An amount quote uses exact token output and returns a maxUnitsIn bound. A shares quote uses exact shares and returns a minTokensOut bound. Full-position quotes require { entireAmount: true, account }; the matching transaction uses the configured wallet account, and an optional account must match that wallet. The returned SyncWithdrawQuote is directly assignable to the exported SyncWithdrawQuoteBounds accepted by getWithdrawTx. Redeem quotes also include shareSafeTokensOut, the largest exact-token withdrawal that preserves slippage headroom within the quoted shares. capacity.knownLiquidityTokens reports the vault's token balance only when no pull-funds calldata can source more liquidity; otherwise it is undefined.

Supplying syncWithdrawQuote implies sync mode and validates its vault, chain, token, account, slippage, and sizing request. When transaction slippage is omitted, the builder uses the quote's slippage; an explicitly supplied value must match. A shares or entireAmount quote with slippageBps: 10000 is rejected because it would produce minTokensOut: 0.

Live capability checks also apply the V2 solving gate. While the gate pauses the provisioner/token pair, both sync flags are false and sync quote or transaction requests are rejected.

Common failures are UnsupportedDepositModeError, UnsupportedFeatureError, StalePriceError, InvalidSyncWithdrawBoundError, InvalidWithdrawParamsError, AccountRequiredError, and AccountMismatchError.

REST API (client.api)

client.api is a typed client for the Gauntlet API at api.gauntlet.xyz — indexed vault metrics, user positions with PnL, the wallet activity log, TVL, and token prices. Response types are generated from the service's OpenAPI spec and verified in CI, so they cannot drift.

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

For logical-vault history, use vaultTimeseriesBySlug: each point contains aggregate tvl.usd and total_supply alongside primary-deployment apy_7d, apy_30d, apy_90d, and unit_price. meta.resolved_vault_id identifies that primary. Null values mark missing data and should render as gaps. Use primaryVaultTimeseriesBySlug when all metrics, including TVL, should describe only the primary deployment; that response also includes its native-token TVL.

Vault ids on the API are CAIP-10 ("{chainId}:{address}"); convert to and from manifest vault ids with apiVaultIdFromVaultId / vaultIdFromApiVaultId. Monetary values are human-unit decimal strings; convert exactly with decimalToBigInt / sharesToBigInt (throws instead of rounding).

Transaction and balance safety

Prepared transactions include chainId in both payload and tx. Check the account and chain before signing each step. Rebuild the steps after a wallet account or chain change.

For exact-token withdrawals derived from shareSafeTokensOut, pass maxShares: quote.shares to getWithdrawTx. This cap remains effective after a rate change. The contract rejects a withdrawal that needs more shares.

getUserCurrentBalance reads balances, conversions, and request state at one block. It filters pending requests by the selected token. A multi-asset deployment requires assetSymbol, as getDepositTx does. The default scan covers the configured request lifetime, with a minimum of three days. Use fromBlock to include older requests, including expired requests that still hold escrow. A vault with several deployments also requires chainId with fromBlock. Each result includes blockNumber and fromBlock to identify its scope. pendingWithdraw reports the gross current token value of escrowed shares. It does not promise the settlement payout after multipliers or solver tips.

Activity flows

getActivityFlows stitches the raw activity log into lifecycle-aware flows — Aera async requests are paired with their settlement or refund via request_hash, replacing client-side event-log scanning:

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 });

Settlement polling requires requestTxHash, the transaction hash of the submitted request. This separates a new request from an earlier request with the same correlation hash. Activity helpers reject incomplete pages, rows out of timestamp order, repeated cursors, and invalid lifecycle deltas. Rows carry no event index, so identical rows in one transaction stay separate rows. Position history rejects mixed asset denominations and unmatched escrow. The API client rejects redirects to prevent credential forwarding.

Position history

getPositionHistory replays a wallet's indexed events into a chronological position timeline — running share balance, escrowed pending amounts, and net asset flows:

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

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

Fee wrapper vaults (partners)

Partner fee wrapper vaults are Aera vaults deployed exclusively for one partner, so they are not in the bundled manifest. Register yours with client.setManifest: extend await client.manifest with your vault entry (deployment values provided by Gauntlet) and every SDK function then accepts its vaultId. See the fee wrapper guide for the full example.

Development

src/api/generated.ts is generated from services/gaia/api/openapi.json — regenerate with yarn generate:api-types after API changes; CI fails if it drifts.

版本与发布记录

@gauntlet-xyz/sdk 共发布 12 个版本,首次发布于 2026/04/18;过去 12 个月发布了 12 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.1.1latest2026/11/079 天前
3.0.12026/10/2819 天前
2.5.02026/08/083 个月前
2.3.02026/07/303 个月前
2.0.02026/06/095 个月前
1.0.62026/06/055 个月前

关于 @gauntlet-xyz/sdk 的常见问题

@gauntlet-xyz/sdk 是什么?

Official Gauntlet SDK for vault deposits, withdrawals, and attribution

如何安装 @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 和提交记录判断。