Examples

Initialize

import { GauntletClient } from '@gauntlet-xyz/sdk'
import { createPublicClient, createWalletClient, http, privateKeyToAccount } from 'viem'
import { base } from 'viem/chains'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

const publicClient = createPublicClient({
  chain: base,
  transport: http(process.env.RPC_URL_BASE!),
})

const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(process.env.RPC_URL_BASE!),
})

const client = new GauntletClient({
  evmClients: { [base.id]: publicClient },
  wallet: walletClient,
  builderCode: 'your-builder-code', // issued by Gauntlet — request from the partnerships team
})

Embedded Wallet (Privy)

The SDK reads only wallet.account.address — it never signs. Any viem-compatible wallet works, including embedded wallets from Privy, Dynamic, or similar providers. For Privy, @gauntlet-xyz/sdk/privy sets up the whole client in one call:

import { createGauntletClientFromPrivy } from '@gauntlet-xyz/sdk/privy'
import { http } from 'viem'
import { base } from 'viem/chains'
import { useWallets } from '@privy-io/react-auth'

const { wallets } = useWallets()
const embeddedWallet = wallets.find(w => w.walletClientType === 'privy')

const client = await createGauntletClientFromPrivy({
  wallet: embeddedWallet,
  chains: [base],
  transports: { [base.id]: http(process.env.RPC_URL_BASE!) }, // optional — defaults to public RPC
  builderCode: 'your-builder-code', // issued by Gauntlet — request from the partnerships team
})

For other embedded wallet providers, build the viem clients yourself:

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

const provider = await embeddedWallet.getEthereumProvider()

const publicClient = createPublicClient({ chain: base, transport: http(process.env.RPC_URL_BASE!) })

const walletClient = createWalletClient({
  account: embeddedWallet.address as `0x${string}`,
  chain: base,
  transport: custom(provider),
})

const client = new GauntletClient({
  evmClients: { [base.id]: publicClient },
  wallet: walletClient,
  builderCode: 'your-builder-code', // issued by Gauntlet — request from the partnerships team
})

Deposit

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'

const steps = await getDepositTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n, // 1 USDC (6 decimals)
  receiver: '0xReceiver', // optional, defaults to wallet account
})
// returns:
// [
//   { payload: { type: 'approve', to: '0x...', data: '0x...', account: '0x...' }, tx: { ... } },
//   { payload: { type: 'requestDeposit', to: '0x...', data: '0x...', account: '0x...' }, tx: { ... } }
// ]

// steps must be executed in order — approve before requestDeposit
for (const step of steps) {
  // Estimate gas — simulates exact calldata before broadcast, catches reverts before spending gas
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })

  const hash = await walletClient.sendTransaction({ ...step.payload, gas })

  // Wait for confirmation before the next step — deposit reverts if preceding approve is not mined
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })

  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

Withdraw

import { getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk/evm'

// Withdraw entire position
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  entireAmount: true,
  receiver: '0xReceiver', // optional; assets are sent here instead of the wallet account
})
// returns:
// [
//   { payload: { type: 'requestRedeem', to: '0x...', data: '0x...', account: '0x...' }, tx: { ... } }
// ]

for (const step of steps) {
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })

  const hash = await walletClient.sendTransaction({ ...step.payload, gas })

  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })

  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

import { getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk/evm'

// By shares
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  shares: 500_000000000000000000n,
})

// By asset amount
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 500_000n,
})

Check User Current Balance

getUserCurrentBalance returns a unified view of all three balance states for a vault position. Call it on load and after any deposit or withdrawal transaction to keep your UI in sync.

import { getUserCurrentBalance } from '@gauntlet-xyz/sdk'
import { VaultId } from '@gauntlet-xyz/sdk/evm'

const balances = await getUserCurrentBalance(client, {
  vaultId: VaultId.AeraUsdAlpha,
  address: '0xUser',
})

console.log(balances)
// [
//   {
//     chain: 'base',
//     token: '0xUSDCADDRESS123',
//     decimals: 6
//     pendingDeposit: 0n,
//     balance: 1_000_000n,
//     pendingWithdraw: 0n,
//   },
// ]

After an async deposit

When a user deposits with depositMode: 'async', the amount appears in pendingDeposit while the vault solver queues it. During this time the funds are locked in the provisioner contract and are not yet earning yield. They move to balance once the solver settles the request — usually within 2 hours.

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'
import { getUserCurrentBalance } from '@gauntlet-xyz/sdk'

// Submit the async deposit
const steps = await getDepositTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 500_000n,
  depositMode: 'async',
})

for (const step of steps) {
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })
  const hash = await walletClient.sendTransaction({ ...step.payload, gas })
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })
  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

// funds are locked in pendingDeposit — not yet earning — until solver settles (~2 hours)
const balances = await getUserCurrentBalance(client, {
  vaultId: VaultId.AeraUsdAlpha,
  address: '0xUser',
})

After an async withdrawal

When a user withdraws with depositMode: 'async', the amount moves from balance to pendingWithdraw. During this time the vault shares have been redeemed and the assets are no longer earning yield, but they have not yet been transferred. Once the solver settles the request (usually within 2 hours), the assets become claimable as ERC-20 tokens in the receiver wallet.

import { getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk/evm'
import { getUserCurrentBalance } from '@gauntlet-xyz/sdk'

// Submit the async withdraw
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  entireAmount: true,
  depositMode: 'async',
})

for (const step of steps) {
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })
  const hash = await walletClient.sendTransaction({ ...step.payload, gas })
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })
  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

// assets are in pendingWithdraw — no longer earning — until solver settles (~2 hours)
const balances = await getUserCurrentBalance(client, {
  vaultId: VaultId.AeraUsdAlpha,
  address: '0xUser',
})

Sync deposit and withdrawal

Sync transactions skip the queue. The balance moves immediately — no pendingDeposit or pendingWithdraw. Morpho withdrawals are sync. Aera mode support combines token settings with live runtime gates, so read it before presenting an instant action. When the V2 solving gate pauses a provisioner/token pair, both sync modes are unavailable. On Aera vaults, a sync deposit locks all of the depositor’s vault units for 1 hour; redeeming or transferring them during that window reverts with Aera__UnitsLocked.

import { getDepositTx, getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk/evm'

// Sync deposit with a Morpho vault: balance goes straight to `balance`
const depositSteps = await getDepositTx(client, {
  vaultId: VaultId.BaseUsdcPrime, // Morpho vault — sync mode
  amount: 500_000n,
})

for (const step of depositSteps) {
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })
  const hash = await walletClient.sendTransaction({ ...step.payload, gas })
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })
  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

// Sync withdraw: balance drops from `balance` immediately;
// tokens appear in the receiver wallet right away
const withdrawSteps = await getWithdrawTx(client, {
  vaultId: VaultId.BaseUsdcPrime, // Morpho vault — sync mode
  entireAmount: true,
})

for (const step of withdrawSteps) {
  const gas = await publicClient.estimateGas({
    to: step.payload.to,
    data: step.payload.data,
    account: step.payload.account,
  })
  const hash = await walletClient.sendTransaction({ ...step.payload, gas })
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 })
  if (receipt.status !== 'success') {
    throw new Error(`Transaction reverted: ${step.payload.type}`)
  }
}

Quote and submit an Aera instant withdrawal

Use the same sizing input for the quote and transaction. Passing syncWithdrawQuote makes the transaction sync and pins the quoted on-chain bound. When transaction slippage is omitted, the builder uses the quote’s slippage; an explicitly supplied value must match.

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

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

if (support.syncRedeem) {
  const quote = await getSyncWithdrawQuote(client, {
    vaultId,
    amount: 500_000n, // exact USDC output
    account: account.address, // optional here; includes this account's lock state
    slippageBps: 50,
  })

  if (quote.capacity.exceedsCapacity) {
    throw new Error('Requested amount exceeds the current sync-withdraw epoch capacity')
  }

  const steps = await getWithdrawTx(client, {
    vaultId,
    amount: 500_000n,
    syncWithdrawQuote: quote,
  })

  for (const step of steps) {
    const hash = await walletClient.sendTransaction({
      to: step.payload.to,
      data: step.payload.data,
      account: step.payload.account,
    })
    const receipt = await publicClient.waitForTransactionReceipt({ hash })
    if (receipt.status !== 'success') throw new Error('Sync withdrawal reverted')
  }
}

For a full-position instant exit, the quote requires the account whose shares it reads. The transaction always uses the configured wallet.account; an optional account must match it. The builder rereads the current share balance and rejects a stale full-position quote. shares and entireAmount quotes with slippageBps: 10000 are rejected because they would produce minTokensOut: 0.

const quote = await getSyncWithdrawQuote(client, {
  vaultId: VaultId.AeraUsdAlpha,
  account: account.address,
  entireAmount: true,
})

const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  account: account.address,
  entireAmount: true,
  syncWithdrawQuote: quote,
})

Read Live Vault Data

client.api exposes every REST API endpoint with generated types — live metrics, timeseries, positions, activity, TVL, and prices. No RPC needed; a data-only client is just new GauntletClient({ apiKey }).

import { apiVaultIdFromVaultId } from '@gauntlet-xyz/sdk'
import { VaultId } from '@gauntlet-xyz/sdk/evm'

// All vaults with live TVL / APY / unit price
const { data: vaults } = await client.api.vaults()

// One vault — the API identifies vaults by "{chainId}:{address}"
const apiVaultId = await apiVaultIdFromVaultId(client, VaultId.AeraUsdAlpha)
const { data: vault } = await client.api.vault(apiVaultId)

// 30 days of daily TVL / unit-price / APY history
const { data: points } = await client.api.vaultTimeseries(apiVaultId, {
  start: '2026-06-01',
  end: '2026-07-01',
  granularity: 'day',
})

User positions and PnL:

// All positions for a wallet
const { data: positions } = await client.api.positions('0xUser')

// One position's value / cost-basis / PnL / ROI history
const { data: history } = await client.api.positionTimeseries('0xUser', apiVaultId, {
  granularity: 'day',
})

Amounts are human-unit decimal strings (e.g. "1250.5"). Convert to base units exactly with decimalToBigInt(value, token.decimals) — it throws instead of rounding.

Track Activity and Wait for Settlement

getActivityFlows turns the wallet’s raw activity log into one flow per user action, pairing async request/settle rows automatically:

import { getActivityFlows } from '@gauntlet-xyz/sdk'

const flows = await getActivityFlows(client.api, '0xUser')

for (const flow of flows) {
  console.log(flow.kind, flow.status, flow.assets.decimal, flow.txHashes)
}
// deposit  settled  1000    ['0xrequest...', '0xsettle...']
// withdraw pending  250.5   ['0xrequest...']

After submitting an async deposit or withdrawal, block until the solver settles it:

import { waitForRequestSettlement, SettlementTimeoutError } from '@gauntlet-xyz/sdk'

try {
  const flow = await waitForRequestSettlement(client.api, '0xUser', requestHash)
  console.log(flow.status) // 'settled' or 'refunded'
} catch (e) {
  if (e instanceof SettlementTimeoutError) { /* still pending after 10 minutes — poll again later */ }
}

Position History

Replay a wallet’s full event history for one vault into a chronological timeline — share balance, escrowed pending amounts, and net asset flows after every event:

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

const apiVaultId = await apiVaultIdFromVaultId(client, VaultId.AeraUsdAlpha)
const { points } = await getPositionHistory(client.api, '0xUser', apiVaultId)

const latest = points.at(-1)
console.log(latest?.sharesBalance, latest?.netAssetsIn)

Wagmi / writeContract

When integrating with wagmi, use step.tx fields with writeContractAsync. Pass step.tx.attribution as dataSuffix — wagmi appends it to the calldata before sending. Omitting dataSuffix silently drops attribution: the transaction succeeds but volume is not tracked.

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'
import { useWriteContract } from 'wagmi'

const { writeContractAsync } = useWriteContract()

const steps = await getDepositTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
})

for (const step of steps) {
  await writeContractAsync({
    address: step.tx.address,
    abi: step.tx.abi,
    functionName: step.tx.functionName,
    args: step.tx.args,
    account: step.tx.account,
    dataSuffix: step.tx.attribution, // required — omitting silently drops attribution
  })
}

Slippage

Both getDepositTx and getWithdrawTx accept a slippageBps parameter (integer basis points, e.g. 50 = 0.5%). Defaults to 100 (1%).

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'

const steps = await getDepositTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
  slippageBps: 50, // 0.5% slippage tolerance
})

Error Handling

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'
import {
  VaultNotFoundError,
  AccountRequiredError,
  RpcNotConfiguredError,
  UnsupportedDepositModeError,
  InvalidSlippageBPSError,
  UnimplementedFeatureError,
  UnitConversionError,
} from '@gauntlet-xyz/sdk'

try {
  await getDepositTx(client, {
    vaultId: VaultId.AeraUsdAlpha,
    amount: 1_000_000n,
  })
} catch (e) {
  if (e instanceof VaultNotFoundError)          { /* e.vaultId, e.chainId */ }
  if (e instanceof AccountRequiredError)        { /* add wallet to GauntletClient config */ }
  if (e instanceof RpcNotConfiguredError)       { /* e.chainId — add RPC URL for this chain */ }
  if (e instanceof UnsupportedDepositModeError) { /* e.vaultId, e.requested, e.available */ }
  if (e instanceof InvalidSlippageBPSError)     { /* e.slippage — must be integer 0–10000 */ }
  if (e instanceof UnimplementedFeatureError)   { /* e.feature */ }
  if (e instanceof UnitConversionError)         { /* e.vaultAddress */ }
}

Aera instant quote and quote-bound transaction flows can also throw UnsupportedFeatureError (runtime is not V2 sync capable), StalePriceError, InvalidSyncWithdrawBoundError, or InvalidWithdrawParamsError (sizing or quote context/account mismatch). Full-position flows use AccountRequiredError when the quote omits account, and AccountMismatchError when the account passed with getWithdrawTx({ entireAmount: true }) differs from the configured wallet. Data-path calls throw GauntletApiError on failed requests:

import { GauntletApiError } from '@gauntlet-xyz/sdk'

try {
  await client.api.position('0xUser', apiVaultId)
} catch (e) {
  if (e instanceof GauntletApiError) {
    console.error(e.status, e.code, e.path) // e.g. 404 NOT_FOUND /v1/users/0xUser/positions/...
  }
}

Onboarding

Integrate

SDK

Attribution

API

Agents

Contracts

Initialize

Embedded Wallet (Privy)

Deposit

Withdraw

Check User Current Balance

After an async deposit

After an async withdrawal

Sync deposit and withdrawal

Quote and submit an Aera instant withdrawal

Read Live Vault Data

Track Activity and Wait for Settlement

Position History

Wagmi / writeContract

Slippage

Error Handling

Go Deeper

SDK Reference

Deposit Your First Dollar

​Initialize

​Embedded Wallet (Privy)

​Deposit

​Withdraw

​Check User Current Balance

​After an async deposit

​After an async withdrawal

​Sync deposit and withdrawal

​Quote and submit an Aera instant withdrawal

​Read Live Vault Data

​Track Activity and Wait for Settlement

​Position History

​Wagmi / writeContract

​Slippage

​Error Handling

​Go Deeper

SDK Reference

Deposit Your First Dollar

Initialize

Embedded Wallet (Privy)

Deposit

Withdraw

Check User Current Balance

After an async deposit

After an async withdrawal

Sync deposit and withdrawal

Quote and submit an Aera instant withdrawal

Read Live Vault Data

Track Activity and Wait for Settlement

Position History

Wagmi / writeContract

Slippage

Error Handling

Go Deeper