AugustVaults

The August Vaults Module.

Vault operations class handling multi-chain vault queries and user positions. Supports both EVM and Solana vaults with unified interface.

Extends: AugustBase

Constructors

Constructor

new AugustVaults(baseConfig, solana, sui): AugustVaults

Parameters

Returns

AugustVaults

Overrides

AugustBase.constructor

Properties

Methods

clearWallet()

clearWallet(): void

Remove wallet address from SDK state and monitoring headers.

Returns

void

Inherited from

AugustBase.clearWallet

depositNative()

depositNative(signer, options): Promise<string>

Parameters

Returns

Promise<string>

deposit tx hash

Description

deposit native token (ETH/AVAX/etc) into a vault using MultiAssetNativeDepositWrapper

fetchPointsLeaderboard()

fetchPointsLeaderboard(params?): Promise<any>

Function

fetchPointsLeaderboard fetches the points leaderboard data

Parameters

Returns

Promise<any>

Leaderboard response data

getOriginInfo()

getOriginInfo(options): Promise<IOriginInfo>

Read a SwapRouter origin code's on-chain registration through this instance's provider for chainId. See getOriginInfo for the registration rule and caching.

Parameters

Returns

Promise<IOriginInfo>

IOriginInfo.

Throws

AugustValidationError (INVALID_CHAIN) when no provider is configured for chainId; (INVALID_INPUT) for a malformed code.

Throws

AugustSDKError when the origins(bytes32) read fails.

Worst Case Rpc Calls

1 — one origins(bytes32) read, cached for 5 minutes.

Example

const info = await augustSdk.getOriginInfo({ chainId: 1, originCode });

getStakingPositions()

getStakingPositions(wallet?, chainId?): Promise<IActiveStakingPosition[]>

Function

getStakingPositions gets all available reward staking positions

Parameters

Returns

Promise<IActiveStakingPosition[]>

all available staking positions for connected or passed network(s)

getSwapRouterEligibleVaults()

getSwapRouterEligibleVaults(chainId, options?): Promise<`0x${string}`[]>

Resolve the vaults currently eligible for the any-token SwapRouter deposit surface on a chain — every vault the router has enableVault-ed whose on-chain registration is still live.

Reconstructs the set from the router's VaultEnabled event history and re-checks vaultInfo(vault).referenceAsset != 0 for each (the mapping is not enumerable). See getSwapRouterEligibleVaults for the full two-stage behavior and RPC cost. Uses this instance's configured provider for chainId; returns [] (no RPC) when no router is deployed there or no provider is configured.

On-chain eligibility only — app-level policy (e.g. excluding vaults with their own OVault deposit flow) remains the caller's responsibility.

Parameters

Returns

Promise<`0x${string}`[]>

Checksummed eligible vault addresses; [] when unavailable.

Throws

AugustSDKError when an eth_getLogs scan chunk fails.

Example

const vaults = await augustSdk.getSwapRouterEligibleVaults(1);

getSwapRouterWhitelistedTokens()

getSwapRouterWhitelistedTokens(chainId, options?): Promise<`0x${string}`[]>

Resolve the ERC-20 tokens currently whitelisted for the SwapRouter on a chain — the any-token set a deposit UI can offer as swap-and-deposit inputs, each verified true against the router's on-chain allowlist.

Reconstructs the set from the router's TokenEnabled event history and re-checks whitelistedTokens(token) for each (the mapping is not enumerable). See getSwapRouterWhitelistedTokens for the full two-stage behavior and RPC cost. Uses this instance's configured provider for chainId; returns [] (no RPC) when no router is deployed there or no provider is configured.

Parameters

Returns

Promise<`0x${string}`[]>

Checksummed whitelisted token addresses; [] when unavailable. Callers still exclude a target vault's natively-accepted assets (those deposit without a swap).

Throws

AugustSDKError when an eth_getLogs scan chunk fails.

Example

const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);

getTotalDeposited()

getTotalDeposited(options?): Promise<number>

Calculate total deposited across all tokenized vaults by summing latest_reported_tvl. Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD. Wrapper vaults (non-null underlying_vault_address) are skipped: their deposits sit in the underlying vault as LP and are already counted there.

Parameters

Returns

Promise<number>

Total deposited amount in USD (sum of all latest_reported_tvl values)

getUserHistory()

getUserHistory(__namedParameters): Promise<IVaultUserHistoryItem[]>

Parameters

Returns

Promise<IVaultUserHistoryItem[]>

getUserPoints()

getUserPoints(userAddress): Promise<any>

Function

getUserPoints fetches user points from the backend API

Parameters

Returns

Promise<any>

Points data from the backend API

getUserTransfers()

getUserTransfers(__namedParameters): Promise<object[]>

Parameters

Returns

Promise<object[]>

getVault()

getVault(vault): Promise<IVault>

Fetch detailed data for a single vault with optional enrichment. Automatically includes loans and allocations unless explicitly disabled.

Parameters

Returns

Promise<IVault>

Single vault object with optional position data

Throws

AugustValidationError (INVALID_CHAIN) when chainId is not a chain the SDK recognises, or is a supported EVM chain with no RPC URL configured on this SDK instance.

getVaultActivity()

getVaultActivity(params): Promise<IVaultUserHistoryItem[]>

Fetch a vault's deposit/withdrawal activity across every participant.

This is the vault-wide counterpart to getUserHistory: instead of filtering the subgraph to one wallet, it returns every deposit, withdrawal-request, and processed-withdrawal event for the pool. Use it to answer flow questions ("how many deposits in the last 7 days", "net flow this week") that point-in-time TVL cannot.

Rows are read from the Goldsky subgraph, paginated internally so busy vaults are not truncated at the 1000-row page cap. When sinceTs is supplied the reader stops paging once it passes the window boundary, so a short lookback stays cheap even on high-volume vaults.

Parameters

Returns

Promise<IVaultUserHistoryItem[]>

Activity items sorted oldest-first, each with a normalized amount, actor address, type, and transactionHash.

Throws

If vault is not a valid address, or no chain id can be resolved.

Example

const weekAgo = Math.floor(Date.now() / 1000) - 7 * 86_400;
const deposits = await sdk.getVaultActivity({
  vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA',
  chainId: 143,
  sinceTs: weekAgo,
  types: ['deposit'],
});
console.log(`${deposits.length} deposits in the last 7 days`);

getVaultAllocations()

getVaultAllocations(vault): Promise<IVaultAllocations | { message: string; status: number; }>

Fetch a vault's DeFi / CeFi / OTC allocation breakdown.

Parameters

Returns

Promise<IVaultAllocations | { message: string; status: number; }>

Allocation data for the vault

Throws

AugustValidationError (INVALID_CHAIN) when chainId is not a chain the SDK recognises, or is a supported EVM chain with no RPC URL configured on this SDK instance.

getVaultAnnualizedApy()

getVaultAnnualizedApy(vault): Promise<IVaultAnnualizedApy>

Get annualized APY metrics for a vault.

Supported Vaults: cUSDO, tETH, wstETH, rsETH

Parameters

Returns

Promise<IVaultAnnualizedApy>

Annualized APY data including liquidity APY

getVaultApy()

getVaultApy(vault): Promise<object[]>

Function

Parameters

Returns

Promise<object[]>

a value or array of objects containing the APR and timestamp

getVaultAvailableRedemptions()

getVaultAvailableRedemptions(props): Promise<{ availableRedemptions: IVaultAvailableRedemption[]; pendingRedemptions: IVaultAvailableRedemption[]; processedWithdrawals: ISubgraphWithdrawProccessed[]; requestedWithdrawals: ISubgraphWithdrawRequest[]; }>

A wallet's redemption requests on one vault, split into availableRedemptions and pendingRedemptions. EVM, Stellar and Solana vault addresses are accepted; see AugustSDK.getVaultAvailableRedemptions for what each list holds on Solana.

Parameters

Returns

Promise<{ availableRedemptions: IVaultAvailableRedemption[]; pendingRedemptions: IVaultAvailableRedemption[]; processedWithdrawals: ISubgraphWithdrawProccessed[]; requestedWithdrawals: ISubgraphWithdrawRequest[]; }>

{ availableRedemptions, pendingRedemptions }, plus the verbose lists.

Throws

Error when unauthorized, or when vault is missing or not an address.

getVaultBorrowerHealthFactor()

getVaultBorrowerHealthFactor(chainId?, vault?): Promise<Record<string, IVaultBorrowerHealthFactor[]> | Record<string, IVaultBorrowerHealthFactor[]>[]>

Gets borrower health-factor data for vaults on a chain, optionally scoped to a single vault.

Pass vault whenever the caller knows which pool it cares about — this skips the all-vaults cross-chain fanout and only reads the loans for that one pool. The response map is keyed by lowercased vault address; look entries up with address.toLowerCase().

Individual loan failures (bad/test loan contracts, unrecognized borrowers) are isolated and logged rather than rejecting the batch.

Parameters

Returns

Promise<Record<string, IVaultBorrowerHealthFactor[]> | Record<string, IVaultBorrowerHealthFactor[]>[]>

When chainId is set, an object map of lowercased vault address → array of borrower-health-factor rows. When chainId is omitted, a flat array (legacy behavior, kept for backward compat).

getVaultHistoricalTimeseries()

getVaultHistoricalTimeseries(vault): Promise<IHistoricalTimeseriesResponse>

Function

getVaultHistoricalTimeseries gets historical timeseries data for a vault

Parameters

Returns

Promise<IHistoricalTimeseriesResponse>

Historical timeseries data with TVL, APY, PnL, share price, and other metrics

getVaultLoans()

getVaultLoans(vault): Promise<IVaultLoan[]>

Fetch the active loans issued by a vault.

Parameters

Returns

Promise<IVaultLoan[]>

Loan data for the vault

Throws

AugustValidationError (INVALID_CHAIN) when chainId is not a chain the SDK recognises, or is a supported EVM chain with no RPC URL configured on this SDK instance.

getVaultPendingRedemptions()

getVaultPendingRedemptions(vault): Promise<IVaultPendingRedemptions>

Fetch pending redemptions for a vault with liquidity analysis.

Parameters

Returns

Promise<IVaultPendingRedemptions>

Pending redemptions grouped by date with liquidity summary

getVaultPnl()

getVaultPnl(props): Promise<IVaultPnl>

Get PnL for a vault (vault-level, not user-specific). Returns the vault's overall profit and loss across all users.

Parameters

Returns

Promise<IVaultPnl>

Vault PnL in USD and notional value

getVaultPositions()

getVaultPositions(__namedParameters): Promise<IVaultPosition[]>

Fetch the wallet's positions across vaults — a single vault, one chain, or every chain with a configured provider.

RPC volume (worst case, multi-vault paths): the two non-cacheable per-vault reads (balanceOf, lagDuration) are aggregated into chunked Multicall3 aggregate3 batches per chain (10 calls per chunk) on chains where the canonical deployment is verified; unverified chains (e.g. Citrea 4114) and non-EVM vaults keep one eth_call per read. Measured on a cold cache for a wallet with 62 vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching, 54 after (~35% fewer). A vault whose batched read fails (e.g. paused) falls back to its own per-vault reads — never to a zeroed balance.

Parameters

Returns

Promise<IVaultPosition[]>

getVaultRedemptionHistory()

getVaultRedemptionHistory(vault): Promise<IVaultRedemptionHistoryItem[]>

Historical redemption requests for a vault (settled, cancelled, and pending-but-out-of-window). Filterable by wallet.

Stellar vaults return [] — on-chain redemption history is not yet indexed for that adapter.

Parameters

Returns

Promise<IVaultRedemptionHistoryItem[]>

The same array shape getVaultRedemptionHistory returns at the module level — historical redemption records, newest first.

Example

const history = await sdk.vaultsModule.getVaultRedemptionHistory({
  vault: '0xVault',
  chainId: 8453,
  wallet: '0xWallet',
});

getVaults()

getVaults(options?): Promise<IVault[]>

Fetch all vaults across configured networks with optional enrichment. Automatically filters by available providers and optionally by chain IDs. Includes closed vaults that are still visible (status: 'closed', is_visible: true) so consumers can render positions held in closed vaults; closed vaults with is_visible: false are excluded.

RPC volume (worst case, wallet enrichment path): the per-vault balanceOf/lagDuration reads are aggregated into chunked Multicall3 aggregate3 batches per chain (10 calls per chunk) on chains where the canonical Multicall3 deployment is verified; other chains (e.g. Citrea 4114) keep one eth_call per read. Measured on a cold cache for a wallet with 62 vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching, 54 after (~35% fewer; 124 per-vault eth_calls collapse into ~13 aggregate3 calls — the remaining requests are the per-vault cached decimals/receipt-token reads on a cold cache).

Parameters

Returns

Promise<IVault[]>

Array of vault objects with optional loans/allocations/positions

getVaultSubaccountLoans()

getVaultSubaccountLoans(vault): Promise<IVaultLoan[]>

Fetch a vault's loans broken down by sub-account.

Parameters

Returns

Promise<IVaultLoan[]>

Sub-account loan data for the vault

Throws

AugustValidationError (INVALID_CHAIN) when chainId is not a chain the SDK recognises, or is a supported EVM chain with no RPC URL configured on this SDK instance.

getVaultSummary()

getVaultSummary(vault): Promise<IVaultSummary>

Get summary data for a vault (name, type, chain, recent returns).

Parameters

Returns

Promise<IVaultSummary>

Vault summary data

getVaultTvl()

getVaultTvl(vault): Promise<object[]>

Function

getVaultTvl gets the vault/pool TVL, both current and historical

Parameters

Returns

Promise<object[]>

an object or array of objects containing the TVL and timestamp

getVaultUserLifetimePnl()

getVaultUserLifetimePnl(props): Promise<IVaultUserLifetimePnl>

Get lifetime PnL for a user in a specific vault.

Parameters

Returns

Promise<IVaultUserLifetimePnl>

Lifetime PnL data including realized and unrealized PnL

Throws

AugustHistoryUnavailableError (HISTORY_UNAVAILABLE) when a live position has no indexed deposits, withdrawals or priceable share transfers.

Throws

AugustPriceUnavailableError (PRICE_UNAVAILABLE) when the vault's underlying asset has no USD price.

getVaultWithdrawals()

getVaultWithdrawals(vault, chainId?): Promise<IVaultWithdrawals>

Get withdrawal summary and pending queue for a vault.

Parameters

Returns

Promise<IVaultWithdrawals>

Withdrawal summary and pending queue

getWithdrawalRequestsWithStatus()

getWithdrawalRequestsWithStatus(vault, receiver?, lookbackBlocks?, chainId?): Promise<WithdrawalRequestStatus[]>

Get all withdrawal requests for a vault with deterministic status tracking.

Matches requests to processed events by (receiver, claimableDate) tuple.

Status values:

• 'processed' — Matching WithdrawalProcessed event found on-chain.
• 'ready_to_claim' — Claimable date has passed, no processed event found yet.
• 'pending' — Claimable date is still in the future.

Lookback window: Processed events are fetched from on-chain logs, which only cover a finite block range. Requests whose claimable date is older than this window with no matching processed event are excluded (assumed already processed). Use lookbackBlocks to widen or narrow the scan range.

Parameters

Returns

Promise<WithdrawalRequestStatus[]>

Array of withdrawal requests with status and claimable dates

getYieldLastRealizedOn()

getYieldLastRealizedOn(vault): Promise<number>

Function

getYieldLastRealizedOn gets the timestamp when yield was last realized for a vault

Parameters

Returns

Promise<number>

Timestamp (Unix timestamp in seconds) when yield was last realized

init()

init(): Promise<void>

Verify the configured August API key and mark this instance as authorized. Only for SDKs built with keys.august; a keyless SDK skips init().

Returns

Promise<void>

Throws

Error when keys.august is missing or rejected by the API.

Inherited from

AugustBase.init

previewRedemption()

previewRedemption(vault): Promise<INormalizedNumber>

Preview the amount of assets that would be received for redeeming shares (queued redemption).

Parameters

Returns

Promise<INormalizedNumber>

The amount of assets as INormalizedNumber { normalized, raw }

previewRwaRedemption()

previewRwaRedemption(vault): Promise<INormalizedNumber>

Preview the output amount for an RWA instant redemption. Resolves the vault address to the RwaRedeemSubaccount internally.

Parameters

Returns

Promise<INormalizedNumber>

normalized number of the expected output amount (in output asset decimals)

registerUserForPoints()

registerUserForPoints(userAddress, referrerAddress, chainId, signature, nonce, expiry): Promise<Response>

Register a user for the points program, authenticated by a wallet signature.

The caller produces a personal_sign signature over a canonical message built from these primitives — see registerUserForPoints in ./getters for the exact template and a worked example.

Parameters

Returns

Promise<Response>

Raw Response from the backend.

rwaRedeemAsset()

rwaRedeemAsset(signer, vault): Promise<string>

Redeem vault shares for an underlying asset via instant redemption (RWA subaccount). Resolves the vault address to the RwaRedeemSubaccount internally. Handles vault share approval automatically.

Parameters

Returns

Promise<string>

transaction hash

switchNetwork()

switchNetwork(chainId): void

Switch the active blockchain network. Updates both chain ID and RPC URL for subsequent operations.

Parameters

Returns

void

Inherited from

AugustBase.switchNetwork

updateWallet()

updateWallet(address): void

Set active wallet address and update monitoring headers. Preserves existing environment setting.

Parameters

Returns

void

Inherited from

AugustBase.updateWallet

vaultDeposit()

vaultDeposit(signer, options): Promise<string>

Parameters

Returns

Promise<string>

deposit tx hash

Description

deposit underlying token into the specified pool with adapter support. This is for when we cannot pass in a signer in sdk and need to do so as an arg

Interfaces

CountWithdrawalRequestsOnceParams

Inputs countWithdrawalRequestsOnce reads.

Properties

HistoryCoversMintsParams

Inputs historyCoversMints compares.

Properties

IGetVaultsOptions

Options accepted by getVaults — on both the AugustSDK facade and the underlying AugustVaults module. Defined once so the two signatures cannot drift (the facade previously declared a narrower inline type that rejected documented options like includeClosed at compile time).

Extends: IVaultCustomOptions

Properties

IVaultBaseOptions

Base configuration for vault operations.

Properties

IVaultCustomOptions

Optional enrichment options for vault queries.

Extended by

• IGetVaultsOptions

Properties

PnlCostBasis

The cost basis getVaultUserLifetimePnl computes PnL against.

Properties

PnlCostBasisParams

Inputs pnlCostBasis folds together.

Properties

PnlHistoryConsistencyParams

Inputs the lifetime-PnL history guard inspects.

Properties

PnlTokenPriceParams

Inputs the lifetime-PnL price guard inspects.

Properties

SelectReserveDepositsParams

Inputs selectReserveDeposits matches.

Properties

SettleV2RedemptionsParams

Inputs settleV2Redemptions values.

Properties

TransferCostBasis

Asset amounts that peer transfers moved into and out of a position.

Properties

TransferCostBasisParams

Inputs transferCostBasis prices.

Properties

V2RedemptionValue

What a wallet's Tokenized Vault V2 redemption requests are worth.

Properties

WithdrawalRequestStatus

Withdrawal request with computed claimable date and current processing status. The unique identifier is (receiver, claimableDate).

WithdrawalRequestStatus

Properties

Type Aliases

PnlTransfer

PnlTransfer = Pick<ISubgraphTransfer, "from" | "to" | "value" | "timestamp_">

The receipt-token transfer fields the transfer cost basis reads.

Functions

assertPnlHistoryConsistent()

assertPnlHistoryConsistent(params): void

Guard against lifetime-PnL over-inflation when the deposit history fails to load.

Lifetime PnL is currentPosition + totalWithdrawn - totalDeposited. When the deposit/withdrawal history fails to load it collapses to empty, so both totalDeposited and totalWithdrawn read as zero. If the wallet still holds a live on-chain position, the formula degenerates to reporting the entire position as pure profit — a plausible-looking but wrong number.

This guard rejects exactly that state: a non-zero position with no recorded deposits, no shares received by transfer and no recorded withdrawals. It also rejects a non-zero position with no recorded deposits when a share mint to the wallet has no matching deposit (mintsMatchHistory: false): the mint proves a deposit the history failed to return, so neither a peer transfer nor a withdrawal makes the cost basis complete. Otherwise, any of the following is treated as consistent and passes:

• deposits are present (the normal, computable case);
• shares were received by transfer and priced (see transferCostBasis);
• withdrawals are present (a fully-exited-then-re-entered position is still computable — the withdrawal records prove history loaded);
• the current position is zero (the wallet never interacted or fully exited, so a zero PnL is correct, not inflated).

Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot path with no added latency.

Shares received by a direct token transfer (never deposited, never withdrew) reach this guard as receivedByTransferRaw: getVaultUserLifetimePnl prices them with transferCostBasis first. The guard still throws for such a wallet when its transfers cannot be read or priced, or when a share mint to it has no indexed deposit.

Parameters

Returns

void

void when the history is consistent.

Throws

AugustHistoryUnavailableError with code HISTORY_UNAVAILABLE and context: { vault, wallet } when a non-zero position has no deposits recorded and either a share mint without a matching deposit or neither received shares nor withdrawals. The message carries the #getVaultUserLifetimePnl::<vault>::<wallet> prefix so it groups with the other errors leaving the getter.

Example

assertPnlHistoryConsistent({
  vault,
  wallet,
  hasDeposits: depositsByAsset.size > 0,
  mintsMatchHistory,
  receivedByTransferRaw: costBasis.receivedByTransferRaw,
  totalWithdrawnRaw,
  currentPositionRaw: currentPositionValue.raw,
});

assertPnlTokenPrice()

assertPnlTokenPrice(params): number

Guard against converting lifetime PnL to USD with a fabricated price.

Every USD field getVaultUserLifetimePnl returns is a native amount times the underlying asset's USD price. When the price server has no price, the only honest outcome is "no USD value" — substituting a stand-in (the getter previously used 1) reports a non-dollar vault's position at $1 per asset, a plausible-looking but wrong number that callers cannot detect.

Pure and synchronous — no RPC, no I/O.

Parameters

Returns

number

tokenPriceUsd, unchanged, when it is a finite number above zero.

Throws

AugustPriceUnavailableError with code PRICE_UNAVAILABLE and context: { vault, wallet, asset } when the price is zero, negative, or not finite. The message carries the #getVaultUserLifetimePnl::<vault>::<wallet> prefix so it groups with the other errors leaving the getter.

Example

const price = assertPnlTokenPrice({
  vault,
  wallet,
  asset: underlyingAssetAddress,
  tokenPriceUsd: await pricePromise,
});

countWithdrawalRequestsOnce()

countWithdrawalRequestsOnce(params): ISubgraphUserHistoryItem[]

Drop withdrawal-request rows the vault logged more than once for a single request.

A redemption requested through Kelp's gain adapter makes High Growth ETH emit WithdrawalRequested twice for one share transfer, and the subgraph indexes both. In a transaction where the share ledger shows the wallet sending shares to the vault n times, at most n request rows are kept. A transaction the ledger shows no such transfer for keeps every row, so a missing ledger leaves the history unchanged.

Pure and synchronous. Hashes and addresses compare case-insensitively.

Parameters

Returns

ISubgraphUserHistoryItem[]

The history without the surplus request rows, in input order.

Example

const history = countWithdrawalRequestsOnce({ history: userHistory, transfers, wallet, vault });

fetchPointsLeaderboard()

fetchPointsLeaderboard(params): Promise<any>

Fetch the points leaderboard data.

Parameters

Returns

Promise<any>

Leaderboard response data

getHealthFactorOfBorrowersByVault()

getHealthFactorOfBorrowersByVault(options): Promise<Record<string, IVaultBorrowerHealthFactor[]>>

Aggregate borrower-health-factor data, optionally scoped to a single vault.

• When vault is provided, only that vault's tokenized record is fetched and only its loans are read. This is the path callers should use when they already know which vault they care about — it skips the cross-chain fanout entirely.
• When vault is omitted, the function fetches every tokenized vault and builds health factors for each, preserving the legacy behavior. Per-vault failures are isolated with Promise.allSettled so one bad vault returns an empty array instead of rejecting the whole map.

The returned map is keyed by lowercased vault address so callers can look up entries without worrying about EIP-55 checksum casing in either the backend response or the caller's input.

Parameters

Returns

Promise<Record<string, IVaultBorrowerHealthFactor[]>>

Map of lowercased vault address → array of borrower-health-factor rows.

getPreviewRedemption()

getPreviewRedemption(vault): Promise<INormalizedNumber>

Preview the amount of assets that would be received for redeeming shares (queued redemption).

Parameters

Returns

Promise<INormalizedNumber>

The amount of assets as an INormalizedNumber with normalized and raw fields

getRewardsStakingPositions()

getRewardsStakingPositions(__namedParameters): Promise<IActiveStakingPosition[]>

Parameters

Returns

Promise<IActiveStakingPosition[]>

getSwapRouterDepositResult()

getSwapRouterDepositResult(signer, options): Promise<ISwapRouterDepositResult>

Resolves the real, post-execution outcome of a SwapRouter deposit from its mined transaction receipt. The SwapRouter contract itself emits no deposit/amount-out event — only the vault does, via its own Deposit event — so this decodes that log directly rather than trusting the pre-trade quote a UI shows before the user submits (the true post-swap amount depends on execution-time price and can differ from that estimate).

Works for both vault generations without the caller resolving the version first: evm-1 (ERC-4626-style Deposit(sender, owner, assets, shares)) and evm-2 (Deposit(assetIn, amountIn, shares, senderAddr, receiverAddr)) have different event signatures (different topic0), so both are registered and whichever matches the vault's actual log is decoded.

Parameters

Returns

Promise<ISwapRouterDepositResult>

The decoded ISwapRouterDepositResult, or null if the receipt isn't found yet or carries no Deposit log from vault (e.g. the hash is wrong, or the tx hasn't mined).

Throws

AugustValidationError if signer has no connected provider.

Worst Case Rpc Calls

1 — a single getTransactionReceipt call; decoding is local.

Example

const hash = await augustSdk.evm.swapRouterDeposit({ ... });
const result = await augustSdk.evm.getSwapRouterDepositResult({
  txHash: hash,
  vault: '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
});
// result?.amountOut — actual reference-asset amount received after the swap

getUserPoints()

getUserPoints(userAddress): Promise<any>

Fetch user points from the backend API endpoint. This replaces client-side points calculation with server-side processing.

Parameters

Returns

Promise<any>

Points data from the backend API

getVault()

getVault(vault): Promise<IVault>

Fetch comprehensive vault data including on-chain state and backend metadata. Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version. Optionally enriches with loan and allocation data.

Parameters

Returns

Promise<IVault>

Complete vault object with optional enrichments

getVaultAllocations()

getVaultAllocations(vault, options, tokenizedVault?): Promise<IVaultAllocations>

Fetch comprehensive vault asset allocation breakdown. Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans. Categorizes exposures by borrowing, supplying, lending, and wallet holdings.

DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API — one vault-level call covering the idle buffer, Stellar protocol positions, custody wallets, and capital bridged to other chains. The Stellar path adds exactly 1 HTTP call and zero for every other chain; when it fails, the exposure section comes back empty and the CeFi, OTC and loan allocations are still returned.

Parameters

Returns

Promise<IVaultAllocations>

Detailed allocation data with exposure categorization

getVaultAnnualizedApy()

getVaultAnnualizedApy(vault): Promise<IVaultAnnualizedApy>

Fetch annualized APY metrics for a vault.

Supported Vaults: cUSDO, tETH, wstETH, rsETH

Parameters

Returns

Promise<IVaultAnnualizedApy>

Annualized APY data including liquidity APY

getVaultApy()

getVaultApy(__namedParameters): Promise<object[]>

Parameters

Returns

Promise<object[]>

getVaultAvailableRedemptions()

getVaultAvailableRedemptions(__namedParameters): Promise<{ availableRedemptions: IVaultAvailableRedemption[]; pendingRedemptions: IVaultAvailableRedemption[]; processedWithdrawals: ISubgraphWithdrawProccessed[]; requestedWithdrawals: ISubgraphWithdrawRequest[]; }>

Parameters

Returns

Promise<{ availableRedemptions: IVaultAvailableRedemption[]; pendingRedemptions: IVaultAvailableRedemption[]; processedWithdrawals: ISubgraphWithdrawProccessed[]; requestedWithdrawals: ISubgraphWithdrawRequest[]; }>

getVaultBorrowerHealthFactor()

getVaultBorrowerHealthFactor(vault): Promise<IVaultBorrowerHealthFactor[]>

Build the per-loan borrower / health-factor list for a single vault.

Resilience: individual loan reads (loanState(), borrower()) and the per-borrower August backend call are isolated with Promise.allSettled and try/catch so one bad loan — a test loan whose address isn't a real contract, a borrower the backend doesn't recognize, an intermittent RPC error — drops that single row from the result instead of rejecting the whole batch. Failed rows are logged via Logger.log.warn; the loan is still returned with health_factor: undefined so callers can render an explicit empty state rather than a perpetual loading skeleton.

Parameters

Returns

Promise<IVaultBorrowerHealthFactor[]>

Array of IVaultBorrowerHealthFactor, one entry per active loan.

getVaultHistoricalTimeseries()

getVaultHistoricalTimeseries(__namedParameters): Promise<IHistoricalTimeseriesResponse>

Parameters

Returns

Promise<IHistoricalTimeseriesResponse>

getVaultLoans()

getVaultLoans(vault, options): Promise<IVaultLoan[]>

Vault Loans

Parameters

Returns

Promise<IVaultLoan[]>

getVaultPendingRedemptions()

getVaultPendingRedemptions(vault): Promise<IVaultPendingRedemptions>

Fetch pending redemptions for a vault with liquidity analysis.

Parameters

Returns

Promise<IVaultPendingRedemptions>

Pending redemptions grouped by date with liquidity summary

getVaultPnl()

getVaultPnl(vault): Promise<IVaultPnl>

Calculate PnL for a vault (vault-level, not user-specific). Returns the vault's overall profit and loss across all users.

Sums, over the vault's whole history, each day's change in assets per share times that day's total shares, then prices the result at the receipt token's current USD price. The daily history comes from GET /tokenized_vault/{vault}/historical-timeseries, the replacement for the deprecated load_snapshots flag on the vault read.

Network: one backend vault read, one timeseries read and one price read.

Parameters

Returns

Promise<IVaultPnl>

Vault PnL in the deposit asset (totalPnl) and in USD (pnlUsd). Both are zero for a vault with no recorded history. pnlUsd is also zero when the receipt token price cannot be fetched.

Throws

Error when vault is missing, is a Stellar vault, is not an address, or the vault or its history cannot be read.

getVaultPositions()

getVaultPositions(__namedParameters): Promise<IVaultPosition[]>

Vault Positions

Parameters

Returns

Promise<IVaultPosition[]>

getVaultRedemptionHistory()

getVaultRedemptionHistory(__namedParameters): Promise<IVaultRedemptionHistoryItem[]>

Parameters

Returns

Promise<IVaultRedemptionHistoryItem[]>

getVaultSubaccountLoans()

getVaultSubaccountLoans(vault, options): Promise<IVaultLoan[]>

Vault Subaccount Loans

Parameters

Returns

Promise<IVaultLoan[]>

getVaultSummary()

getVaultSummary(vault): Promise<IVaultSummary>

Fetch summary data for a vault (name, type, chain, recent returns).

Parameters

Returns

Promise<IVaultSummary>

Vault summary data

getVaultTvl()

getVaultTvl(__namedParameters): Promise<object[]>

Parameters

Returns

Promise<object[]>

getVaultUserLifetimePnl()

getVaultUserLifetimePnl(vault): Promise<IVaultUserLifetimePnl>

Calculate lifetime PnL for a user in a specific vault.

Basic logic:

1. Get user's list of deposits and withdrawals from subgraph
2. Fetch user's current assets (balanceOf * sharePrice via convertToAssets)
3. Calculate PnL = assets withdrawn + current assets - assets deposited

totalDeposited is the face value of what the user actually paid in (each deposited asset's raw amount, rescaled to the vault's decimals — no live price conversion), so any entry/exit fee the vault charges is automatically counted as a cost against PnL rather than excluded from it. Pre-deposit multi-asset vaults are assumed to only accept dollar-pegged stablecoins into a dollar-denominated vault; a vault accepting a non-pegged deposit asset would need deposit-time price conversion, which this function does not perform.

Every USD field is the native amount times the underlying asset's USD price from the price server. There is no stand-in price: when none resolves the getter throws rather than returning USD values it cannot know.

Shares moved by transfer: peer transfers of the share token (see selectPeerTransfers) are valued at the vault's daily share ratio (transferCostBasis) and folded in by pnlCostBasis — received shares add to totalDeposited (and are reported again as receivedByTransfer), sent shares add to totalWithdrawn. This holds alongside indexed deposits, so a wallet that received shares and also deposited is not credited with the received shares as profit. On LayerZero OVaults, transfers from or to the hub composer and share OFT do not count, because the composer delivers cross-chain deposits by transfer and those are already counted as LayerZero deposits.

Gaps in the indexed history: a share mint with no Deposit event counts as a deposit of the assets in its ReserveDeposit event (selectReserveDeposits; High Growth ETH emits it for Kelp gain-adapter deposits), and a withdrawal request the vault logged twice counts once (countWithdrawalRequestsOnce). Transfers fold in for a depositor only once every mint is explained. A wallet with no indexed deposit and a mint that no deposit explains throws HISTORY_UNAVAILABLE.

Tokenized Vault V2 redemptions carry only shares, so a settled one counts at the assets the vault paid, or at the share ratio on its claim date when the subgraph has no processed row for it (settleV2Redemptions). Only a request not yet claimable is valued at the current share price. When the lag or the ratio history cannot be read, every request is valued at the current share price instead.

Request cost: one receipt-transfer subgraph query (and a symbol() RPC read) per call, plus one backend timeseries request when peer transfers exist and one reserveDeposits subgraph query when a mint has no indexed deposit, and for a Tokenized Vault V2 wallet with redemption requests, a lagDuration() read plus one backend timeseries request. A timeseries window with no usable ratio (a closed vault whose history stopped earlier) is read again in full, so the latest earlier day still prices it. The transfer query runs for every vault, in parallel with the history read.

Parameters

Returns

Promise<IVaultUserLifetimePnl>

Lifetime PnL data in both native token and USD

Throws

AugustHistoryUnavailableError (HISTORY_UNAVAILABLE) when a live position has no indexed deposits, withdrawals or priceable share transfers, or has no indexed deposit while a share mint to the wallet has no matching deposit.

Throws

AugustPriceUnavailableError (PRICE_UNAVAILABLE) when the underlying asset has no USD price, or asset() cannot be read.

getVaultWithdrawals()

getVaultWithdrawals(vault): Promise<IVaultWithdrawals>

Fetch withdrawal summary and pending queue for a vault.

Parameters

Returns

Promise<IVaultWithdrawals>

Withdrawal summary and pending queue

getWithdrawalRequestsWithStatus()

getWithdrawalRequestsWithStatus(params): Promise<WithdrawalRequestStatus[]>

Returns all withdrawal requests for a vault, enriched with computed claimable dates and current processing status.

The unique identifier for matching requests to processed events is: (receiver, claimableDate.year, claimableDate.month, claimableDate.day)

This is the primary method for integrators to reliably track withdrawal status when multiple requests are submitted by the same receiver.

Data sources

• Withdrawal requests come from the subgraph (all historical requests).
• Processed events come from on-chain WithdrawalProcessed logs, which are limited to a finite lookback window determined by the chain's block parameters.

Lookback window & filtering

On-chain logs only cover a limited number of recent blocks (e.g. ~20 days on Monad, ~21 days on Ethereum). The lookbackBlocks parameter controls how far back to scan and is applied uniformly to both data sources: it bounds the WithdrawalProcessed log query and drops any withdrawal request whose submission timestamp falls outside the window — regardless of whether a matching processed event was found. Callers who need deeper history should widen lookbackBlocks.

Status determination

• 'processed' — A matching WithdrawalProcessed event was found (by receiver + claimable date).
• 'ready_to_claim' — Claimable date has passed (within the lookback window) but no processed event found.
• 'pending' — Claimable date is still in the future.

Parameters

Returns

Promise<WithdrawalRequestStatus[]>

Array of withdrawal requests with status and claimable dates

Example

const requests = await getWithdrawalRequestsWithStatus({
  vault: '0xVault...',
  receiver: '0xReceiver...'
});

// Results show exact status + claimable date
requests.forEach(req => {
  console.log(
    `${req.claimableDate.year}-${req.claimableDate.month}-${req.claimableDate.day}: ${req.status}`
  );
});

// With custom lookback window (e.g. 30 days on Ethereum ≈ 216,000 blocks)
const moreResults = await getWithdrawalRequestsWithStatus({
  vault: '0xVault...',
  lookbackBlocks: 216_000,
});

getYieldLastRealizedOn()

getYieldLastRealizedOn(vault): Promise<number>

Fetch the timestamp when yield was last realized for a vault. Returns the assetsUpdatedOn timestamp from the vault contract.

Parameters

Returns

Promise<number>

Timestamp (Unix timestamp in seconds) when yield was last realized

historyCoversMints()

historyCoversMints(params): boolean

Check that a wallet's indexed deposit history accounts for every share mint its share-token ledger shows.

A deposit mints shares to the wallet in the same transaction, so a mint with no deposit of the same hash means the history is missing that deposit (an older deposit the subgraph never indexed, or one a third party made for the wallet). Folding peer transfers into such a history would credit the wallet for shares it sent while missing what it paid for them, so getVaultUserLifetimePnl only folds transfers for a depositor when this holds.

Pure and synchronous. Hashes and addresses compare case-insensitively.

Parameters

Returns

boolean

true when every mint to wallet has a matching deposit, including when there are no mints.

Example

const covered = historyCoversMints({
  transfers,
  wallet,
  depositTransactionHashes: history
    .filter((item) => item.type === 'deposit')
    .map((item) => item.transactionHash_),
});

pnlCostBasis()

pnlCostBasis(params): PnlCostBasis

Fold peer share transfers into a wallet's lifetime-PnL cost basis.

Shares a wallet received from another holder (a migration airdrop, a DEX purchase, a transfer from another wallet) cost the wallet their value on arrival, so they add to the deposited amount; shares it sent away count as withdrawn. This applies whether or not the wallet also deposited, so a holder who received shares and then topped up is not credited with the received shares as profit, and a depositor who moved its shares elsewhere (a lending market, a DEX) is not shown as having lost them. A wallet with no deposit and no received shares keeps a zero basis, so the history guard still decides.

A depositor whose history misses a mint (historyCoversMints) is the exception: its transfers do not count, so the result matches what the getter returned before transfers counted for depositors. A wallet with no deposit still gets a basis here when its history misses a mint, but assertPnlHistoryConsistent rejects it. On a LayerZero OVault the caller leaves the hub composer and share OFT out of the transfers (see selectPeerTransfers): the composer's deliveries are already counted as LayerZero deposits, and shares bridged to a spoke chain still count in the position.

Pure and synchronous.

Parameters

Returns

PnlCostBasis

The deposited and withdrawn amounts to compute PnL from, and the transfer-priced part of the deposited amount (zero when transfers did not count).

Example

const basis = pnlCostBasis({
  depositedRaw,
  withdrawnAssetsRaw,
  hasDeposits: depositedRaw > BigInt(0),
  mintsMatchHistory: historyCoversMints({
    transfers,
    wallet,
    depositTransactionHashes,
  }),
  transfers: transferCostBasis({
    transfers,
    wallet,
    vault,
    history,
    countSentWithoutReceipt: true,
  }),
});

registerUserForPoints()

registerUserForPoints(userAddress): Promise<Response>

Register a user for the points program, authenticated by a wallet signature.

The caller must obtain a personal_sign (EIP-191) signature over the canonical message template below — the backend reconstructs the same string from these fields and verifies the signature recovers to userAddress. Building the message client-side and server-side from the same primitives means a hostile client cannot show one message in the wallet prompt while submitting a different one for validation.

Canonical message (\n-separated, no trailing newline):

Upshift: register {userAddress.toLowerCase()}
referrer: {referrerAddress.toLowerCase() || "none"}
chain: {chainId}
nonce: {nonce}
expires: {expiry}

Parameters

Returns

Promise<Response>

Raw Response from the backend. 200 on success, 401 for expired / replayed / mismatched-signer / tampered-referrer, 422 for an unsupported chainId.

Example

const nonce = crypto.randomUUID().replace(/-/g, '');
const expiry = Math.floor(Date.now() / 1000) + 300;
const message =
  `Upshift: register ${address.toLowerCase()}\n` +
  `referrer: ${referrer?.toLowerCase() ?? 'none'}\n` +
  `chain: ${chainId}\n` +
  `nonce: ${nonce}\n` +
  `expires: ${expiry}`;
const signature = await walletClient.signMessage({ account: address, message });
await registerUserForPoints({ userAddress: address, referrerAddress: referrer, chainId, signature, nonce, expiry });

selectPeerTransfers()

selectPeerTransfers<T>(transfers, wallet, vault, exclude?): T[]

Keep the receipt-token transfers that moved shares between wallet and another holder.

Vault shares are transferable ERC-20 tokens, so a wallet can hold a position it never deposited into — a migration airdrop, a DEX purchase, a transfer from another wallet. Mints (from the zero address), burns (to it) and transfers to or from the vault itself are dropped: those are the deposit and withdrawal legs the subgraph history already records, and counting them again would double the cost basis. Transfers to or from exclude are dropped too.

Type Parameters

Parameters

Returns

T[]

The peer-to-peer transfers, in input order. Addresses compare case-insensitively.

Example

const peer = selectPeerTransfers(transfers, wallet, vault);

selectReserveDeposits()

selectReserveDeposits(params): ISubgraphReserveDeposit[]

Keep the ReserveDeposit events that explain a share mint the indexed deposit history misses.

High Growth ETH mints shares for deposits made through Kelp's gain adapter with a ReserveDeposit event instead of an ERC-4626 Deposit, so those deposits are absent from the user history and fail historyCoversMints. An event counts only when its transaction mints shares to wallet and holds no indexed deposit, so a deposit is never counted twice.

Pure and synchronous. Hashes and addresses compare case-insensitively.

Parameters

Returns

ISubgraphReserveDeposit[]

The matching events, in input order.

Example

const reserve = selectReserveDeposits({
  reserveDeposits: await getSubgraphUserReserveDeposits(wallet, provider, vault),
  transfers,
  wallet,
  depositTransactionHashes,
});

settleV2Redemptions()

settleV2Redemptions(params): V2RedemptionValue

Value a wallet's Tokenized Vault V2 redemption requests, which carry only shares.

Every processed withdrawal (WithdrawalProcessed.assetsAmount) counts at the assets the vault paid. Its shares, estimated at the vault's asset_share_ratio on the day it was processed, retire the oldest requests first. Request shares left over count at the ratio on their claim date (see computeClaimableDate) once claimable: the subgraph lacks some processed rows (none for earnAUSD before 2026-02-01), and that ratio lands within about 0.05% of what the vault paid. Shares not yet claimable are left to the current share price. Matching by amount, not by claim date, keeps the result right when a vault processes a request before the date today's lagDuration implies. A leftover under 0.5% of a request that a later processed withdrawal followed is rounding from the daily ratio, so it is dropped.

Pure and synchronous. Assumes, as the getter does, that shares and assets share the vault's decimals. A day with no usable ratio takes the latest earlier day's, and a date older than the history takes the earliest day's.

Parameters

Returns

V2RedemptionValue

The settled assets and the shares left to the current price; every requested share is pending when ratios holds no usable day.

Example

const { settledAssetsRaw, pendingShares } = settleV2Redemptions({
  history,
  lagDuration: 259_200,
  ratios: (await fetchVaultHistoricalTimeseries(vault, nDays)).data,
  now: Math.floor(Date.now() / 1000),
});

sumDepositsAtFaceValue()

sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals): bigint

Sum a wallet's per-asset deposits into the vault's own decimals, at face value — 1 unit of any deposited asset is treated as 1 unit of the vault's reporting currency, with no live price conversion.

Used by getVaultUserLifetimePnl for totalDeposited. Pre-deposit multi-asset vaults only accept dollar-pegged stablecoins (USDC, USDT, DAI, USDS, RLUSD, etc.) into a dollar-denominated vault, so face value is a reasonable stand-in for USD value. This intentionally does NOT re-quote through a live price oracle: doing so priced a historical deposit at today's market rate, so totalDeposited (and lifetimePnl) drifted between calls purely from stablecoin peg noise, and approximately re-inflated deposits back toward face value — which silently excluded the vault's entry fee from PnL. The fee is money the user actually paid, so PnL must be computed net of it.

Parameters

Returns

bigint

Total deposited, in raw base units at vaultDecimals.

transferCostBasis()

transferCostBasis(params): TransferCostBasis

Value peer share transfers in the vault's asset, at the vault's share ratio on the day each one happened.

Used by getVaultUserLifetimePnl when a wallet has no indexed deposits: received shares become its cost basis and sent shares count as withdrawn, so lifetime PnL for a transfer recipient reads "PnL since the shares arrived" rather than failing or reporting the whole position as profit. A day with no usable ratio takes the latest earlier day's, and a transfer older than the history takes the earliest day's.

Sent shares count only against a received basis by default. A wallet that sent shares but received none gets a zero basis, so the lifetime-PnL history guard still decides for it instead of reporting the sent shares as profit. countSentWithoutReceipt: true reports them anyway, for a caller that knows the wallet also deposited.

Pure and synchronous. Assumes, as the getter does, that shares and assets share the vault's decimals.

Parameters

Returns

TransferCostBasis

The received and sent asset amounts, raw at the vault's decimals; both zero when no shares were received.

Throws

AugustHistoryUnavailableError (HISTORY_UNAVAILABLE) when no day in history carries a positive, finite asset_share_ratio.

Example

const { data } = await fetchVaultHistoricalTimeseries(vault, nDays);
const { receivedRaw, sentRaw } = transferCostBasis({
  transfers: selectPeerTransfers(transfers, wallet, vault),
  wallet,
  vault,
  history: data,
});

References

default

Renames and re-exports AugustVaults