@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
viemis 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.