SDK Reference

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

const client = new GauntletClient({
  evmClients: {
    [base.id]: createPublicClient({ chain: base, transport: http(process.env.RPC_URL_BASE!) }),
  },
  wallet: createWalletClient({
    account,
    chain: base,
    transport: http(process.env.RPC_URL_BASE!),
  }),
})

import { getVaults } from '@gauntlet-xyz/sdk/evm'
// also available from the root: import { getVaults } from '@gauntlet-xyz/sdk'
import { base } from 'viem/chains'

const candidates = await getVaults(client, { chainId: base.id })
// returns:
// [
//   {
//     vaultId: "baseUsdcPrime",
//     name: "...",
//     protocol: "morpho",
//     deployments: [{ chainId: 8453, supplyToken: [{ symbol: "USDC", ... }], ... }]
//   },
//   ...
// ]

const manifest = await client.manifest

client.setManifest({
  ...manifest,
  vaults: [
    ...manifest.vaults,
    {
      vaultId: 'acmeUsdcFeeWrapper', // any unique id, you choose it
      name: 'Acme USDC',
      protocol: 'aera',
      strategy: 'Fee Wrapper',
      deployments: [
        {
          chain: 'evm',
          chainId: 8453,
          vaultAddress: '0xYourFeeWrapperVault', // provided by Gauntlet
          vaultType: 'multi-depositor',
          supplyToken: [
            {
              address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
              symbol: 'USDC',
              decimals: 6,
            },
          ],
        },
      ],
    },
  ],
})

const steps = await getDepositTx(client, {
  vaultId: 'acmeUsdcFeeWrapper',
  amount: 1_000_000n,
})

import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk/evm'
// also available from the root: import { getDepositTx, VaultId } from '@gauntlet-xyz/sdk'

const steps = await getDepositTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
  receiver: '0xReceiver', // optional, defaults to wallet account
})

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

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

if (support.syncRedeem) {
  // Offer an instant withdrawal.
}

type AeraTokenModeSupport = {
  asyncDeposit: boolean
  asyncRedeem: boolean
  syncDeposit: boolean
  syncRedeem: boolean
}

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

const quote = await getSyncWithdrawQuote(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
  slippageBps: 100,
})

import { getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk/evm'
// also available from the root: import { getWithdrawTx, VaultId } from '@gauntlet-xyz/sdk'

// Withdraw all shares
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  entireAmount: true,
  receiver: '0xReceiver', // optional
})

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

// Withdraw by asset amount
const steps = await getWithdrawTx(client, {
  vaultId: VaultId.AeraUsdAlpha,
  amount: 1_000_000n,
})

const quote = await getSyncWithdrawQuote(client, {
  vaultId: VaultId.AeraUsdAlpha,
  shares: 500_000000000000000000n,
  slippageBps: 50,
})

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

import { getUserCurrentBalance, VaultId } from '@gauntlet-xyz/sdk'
// VaultId also available from: import { VaultId } from '@gauntlet-xyz/sdk/evm'

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

type UserCurrentBalance = {
  chain: string           // chain identifier, e.g. "base" — included for non-EVM compatibility
  token: Address          // token address
  decimals: number        // token decimals
  pendingDeposit: bigint  // assets locked in provisioner after async deposit — not yet earning yield; 0n if none
  balance: bigint         // assets actively earning in the vault; 0n if no position
  pendingWithdraw: bigint // assets redeemed but not yet claimable after async withdraw — no longer earning; 0n if none
}

type PreparedTx = {
  payload: {
    type: string    // 'approve' | 'deposit' | 'requestDeposit' | 'redeem' | 'requestRedeem' | 'withdraw'
    to: Address     // contract to call
    data: Hex       // ABI-encoded calldata with attribution suffix already concatenated
    account?: Address
  }
  tx: EvmTxStep    // structured ABI fields + raw attribution bytes — use with writeContract
}

type EvmTxStep = {
  type: 'approve' | 'deposit' | 'requestDeposit' | 'redeem' | 'requestRedeem' | 'withdraw'
  address: Address        // contract to call
  abi: Abi                // ABI fragment for this call
  functionName: string
  args: readonly unknown[]
  account: Address        // sender address
  attribution?: Hex       // raw attribution bytes — must pass as dataSuffix to writeContract
}

for (const step of steps) {
  await walletClient.sendTransaction(step.payload)
}

for (const step of steps) {
  await walletClient.writeContract({
    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
  })
}

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

const api = new GauntletApi({ apiKey: process.env.GAUNTLET_API_KEY })
const { data: vaults } = await api.vaults()

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

const flows = await getActivityFlows(client.api, '0xUser')
const open = flows.filter(f => f.status === 'pending')

type ActivityFlow = {
  kind: 'deposit' | 'withdraw' | 'transfer_in' | 'transfer_out'
  status: 'settled' | 'pending' | 'refunded'
  vaultId: string          // CAIP-10 id
  requestHash: string | null  // Aera async correlation hash; null for sync flows
  requestedAt: Date | null // when the request row landed
  settledAt: Date | null   // when the settle/refund row landed; null while pending
  assets: AssetAmount      // magnitude of the asset movement (requested amount for refunds)
  shares: bigint           // magnitude of the share movement, 18-decimal base units
  txHashes: string[]       // request first, then settlement
}

type AssetAmount = {
  decimal: string          // human-unit decimal string as the API emits it
  raw: bigint | null       // base-unit integer; null when the token's decimals are unknown
  token: TokenRef | null
}

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

const flow = await waitForRequestSettlement(client.api, '0xUser', requestHash)
// flow.status is 'settled' or 'refunded'

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

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

type PositionHistory = {
  vaultId: string          // CAIP-10 id
  token: TokenRef | null   // the vault's asset token, when known
  points: PositionHistoryPoint[]  // chronological, one per activity row
}

type PositionHistoryPoint = {
  timestamp: Date
  txHash: string
  type: string             // activity row type, e.g. 'deposit', 'withdraw_pending'
  sharesDelta: bigint      // signed share movement of this row, 18-decimal base units
  assetsDelta: string      // signed asset movement, human decimal string
  sharesBalance: bigint    // shares held after this row (escrowed redeem shares excluded)
  pendingDepositAssets: string  // assets escrowed awaiting share mint
  pendingRedeemShares: bigint   // shares escrowed awaiting asset return
  netAssetsIn: string      // cumulative settled deposits minus settled withdrawals
}

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

const { wallets } = useWallets()

const client = await createGauntletClientFromPrivy({
  wallet: wallets[0],
  chains: [base],
  builderCode: 'your-builder-code',
})

type SyncWithdrawQuoteBounds =
  | {
      kind: 'redeem'
      shares: bigint
      minTokensOut: bigint
      context: SyncWithdrawQuoteContext
    }
  | {
      kind: 'withdraw'
      tokensOut: bigint
      maxUnitsIn: bigint
      context: SyncWithdrawQuoteContext
    }

type SyncWithdrawQuote = SyncWithdrawQuoteBounds & {
  shares: bigint
  maxUnitsIn: bigint
  tokensOut: bigint
  minTokensOut: bigint
  rate: SyncRedeemRate
  capacity: SyncWithdrawCapacity
  unitsLockedUntil?: bigint
}

type VaultInfo = {
  vaultId: string
  name: string
  protocol: 'aera' | 'morpho'
  strategy: string
  deployments: VaultDeployment[]
}

type VaultDeployment = {
  chain: 'evm'
  chainId: number
  vaultAddress: Address           // ERC4626 vault contract
  provisionerAddress?: Address    // multi-depositor vaults: deposit routes through this instead
  vaultType: 'single-depositor' | 'multi-depositor'
  depositMode: 'sync' | 'async' | 'both'  // validates the depositMode param in getDepositTx / getWithdrawTx
  supplyToken: TokenInfo[]        // tokens accepted by this vault; provides address and decimals
}

type TokenInfo = {
  symbol: string
  address: Address
  decimals: number
}

type VaultFilter = {
  chainId?: number
  protocol?: string
}

enum AttributionMode {
  PUBLIC  = 'public',
  ENCODED = 'encoded',  // not yet implemented
  PRIVATE = 'private',  // not yet implemented
}