Vault Actions

Overview

The Upshift SDK provides comprehensive vault querying capabilities across all supported chains. Vaults follow the ERC4626 standard and include additional features for loan management, allocations, and user positions.

For detailed vault SDK functions, please refer to the SDK reference page

Vault Versions

Get All Vaults

Fetch all vaults across configured networks with optional enrichment.

import AugustSDK from '@augustdigital/sdk'

const sdk = new AugustSDK({ appName: '<APP_NAME>' })

sdk.getVaults(options?: {
  chainIds?: number[];
  loans?: boolean;
  allocations?: boolean;
  wallet?: string;
  solanaWallet?: string;
}): Promise<IVault[]>

Parameters

Returns

Array of IVault objects

Get Single Vault

Fetch detailed data for a specific vault with optional enrichment.

sdk.getVault({
  vault: string;
  chainId?: number;
  options?: {
    loans?: boolean;
    allocations?: boolean;
    wallet?: string;
    solanaWallet?: string;
  };
}): Promise<IVault>

Parameters

Returns

Single IVault object

Get Vault Loans

Fetch active loan data for a vault (EVM-0 vaults only).

sdk.getVaultLoans({
  vault: string;
  chainId?: number;
}): Promise<IVaultLoan[]>

Returns

Array of loan objects with borrower, principal, interest, and APR data.

Get Vault Allocations

This is the data behind the "Vault Exposure" section on the Upshift app. One call returns exactly what the Upshift UI renders — read exposurePerCategory for the pre-bucketed view (supplying / borrowing / wallet / lending legs plus per-category USD totals). It lives on the root sdk, requires an RPC provider for the vault's chain, and needs keys.august to populate the CeFi/OTC legs. See the Transparency Dashboard section for the per-card methods.

Authentication is required for this function

Fetch DeFi, CeFi, and OTC allocation breakdowns for a vault.

sdk.getVaultAllocations({
  vault: string;
  chainId?: number;
}): Promise<IVaultAllocations>

Returns

Object containing defi, cefi, otc, and tokens arrays.

Transparency Dashboard

Every tab and card of the Upshift per-vault Transparency page is available as an individual read method on sdk.apiModule, so you can compose exactly the subset you want — e.g. the Performance tab without the collateral-ratio card. All methods:

• are public (no API key), one HTTPS request each, zero RPC from the SDK — no providers config needed;
• are snapshot-backed (positions/oracle refresh hourly; cache ≥ 60 s on your side);
• throw AugustValidationError on a bad address / chain id / date / limit before any request is made; non-2xx API responses surface as AugustServerError (AugustRateLimitError on 429, AugustTimeoutError on timeout);
• the chainId-taking methods are EVM-only (Solana/Stellar vaults have no transparency data). getVaultBackingSeries / getVaultSmoothedApy are keyed by vault address alone;
• date windows (startDate / endDate) are YYYY-MM-DD and both inclusive.

Minimal construction — no RPC provider and no API key are needed for anything in this section:

import AugustSDK from '@upshiftfinance/sdk';

const sdk = new AugustSDK({ appName: '<APP_NAME>', keys: {} });

Reproducing the Overview headline numbers

const pos = await sdk.apiModule.getVaultPositionSnapshot({
  vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA',
  chainId: 143,
});

// Headline "Total NAV" on the page is the vault-reported figure from the SAME snapshot:
const headline = pos.reported_tvl ?? pos.total_nav;
// Vault Buffer = liquidity sitting on the vault contract itself:
const deployed = pos.subaccounts.reduce((a, s) => a + s.total_usd, 0);
const vaultBuffer = Math.max(0, pos.total_nav - deployed);
// Every field is from `pos.snapshot_at` — show it as "Last updated".

Notes:

• Borrow legs are negative. In ITransparencyTokenExposure, role: 'borrow' rows carry negative usd_value and balance; a protocol group's total_usd is already the net.
• Pricing follows the published methodology. Hard-pegged stables price at their peg (the same overrides the NAV Oracle tab lists), so total_usd values match the dashboard exactly rather than raw market prices.
• getVaultBackingSeries returns newest-first, hourly points — sort ascending before charting; adjusted_redeem_ratio * 100 is the collateral-ratio percent.
• getVaultSmoothedApy is the ONLY way to match the app's APY charts: the backend applies a rolling-median/mean smoothing filter server-side; recomputing APY locally from share ratios will not match. values are decimal fractions (0.0245 = 2.45%), labels are M/D/YYYY.
• Audit-log pagination: pass before = the last returned entry's timestamp verbatim while has_more is true (exclusive cursor). Audit and timelock timestamps are naive-UTC (no Z); snapshot_at carries one.
• Units: pct_of_nav / pct_of_subaccount / pct_of_tvl are fractions (0.25 = 25%); the fee *_pct fields are already percents (2 = 2%).
• Pending Timelocks is often empty — the default filter is scheduled; pass status: 'all' to show history (the Audit Log covers the same events).
• Governance warnings: Safe / Fordefi enrichment failures degrade rows and append a warning code rather than failing the call — check the array if a role looks incomplete. Codes seen in the wild: safe_api_unavailable, fordefi_api_unavailable, fordefi_partial_coverage (expected — AA subaccounts are never Fordefi keys), timelock_duration_unavailable.

Example — a Performance tab without the collateral-ratio card

const vault = '0x955256B31097dDf47a9E47A95aDfDFB4460D8522';
const [apy, allocations, fees] = await Promise.all([
  sdk.apiModule.getVaultSmoothedApy({ vault, daysAgo: 90 }),
  sdk.apiModule.getVaultHistoricalAllocations({ vault, chainId: 1, startDate: '2026-08-01' }),
  sdk.apiModule.getVaultFeeConfig({ vault, chainId: 1 }),
]);

Get Vault Annualized APY

Fetch annualized APY metrics for specific vaults.

Supported Vaults: cUSDO, tETH, wstETH, rsETH

Deprecation Notice: The hgETH30dLiquidAPY and hgETH7dLiquidAPY response fields are deprecated and will be removed on 2026-01-01. Use liquidAPY30Day and liquidAPY7Day instead.

sdk.getVaultAnnualizedApy({
  vault: string;
}): Promise<IVaultAnnualizedApy>

Parameters

Returns

IVaultAnnualizedApy object with liquidity APY and annualized metrics.

Get Vault Historical Timeseries

Fetch comprehensive historical timeseries data for a vault including TVL, APY, PnL, share price, and other metrics.

sdk.getVaultHistoricalTimeseries({
  vault: string;
  nDays?: number;
}): Promise<IHistoricalTimeseriesResponse>

Parameters

Returns

Historical timeseries data object with date string keys containing TVL, APY, PnL, and share price.

Get Vault TVL

Fetch current or historical total value locked (TVL) for a vault.

sdk.getVaultTvl({
  vault: string;
  chainId?: number;
  historical?: {
    daysAgo?: number;
    order?: 'asc' | 'desc';
    interval?: 'days' | 'weeks' | 'months' | 'years';
  };
}): Promise<{ value: INormalizedNumber; timestamp: string }[]>

Returns

Array of TVL data points with timestamps.

Get Vault Positions

Fetch user positions across one or all vaults.

sdk.getVaultPositions({
  vault?: string;
  wallet?: string;
  chainId?: number;
  showAllVaults?: boolean;
  solanaWallet?: string;
}): Promise<IVaultPosition[]>

Parameters

Returns

Array of vault position objects.

Get Available Redemptions

Fetch claimable redemption requests for a vault and wallet.

sdk.getVaultAvailableRedemptions({
  vault: string;
  chainId?: number;
  wallet?: string;
  verbose?: boolean;
}): Promise<{
  availableRedemptions: IVaultAvailableRedemption[];
  pendingRedemptions: IVaultAvailableRedemption[];
}>

Returns

Object with availableRedemptions (ready to claim) and pendingRedemptions (waiting for lag period).

Get Vault Withdrawals

Fetch withdrawal summary and pending withdrawal queue for a vault.

sdk.getVaultWithdrawals({
  vault: string;
  chainId?: number;
}): Promise<IVaultWithdrawals>

Parameters

Returns

IVaultWithdrawals object containing total withdrawals and pending queue.

Get Vault PnL

Fetch vault-level profit and loss (not user-specific).

sdk.getVaultPnl({
  vault: string;
  chainId?: number;
}): Promise<IVaultPnl>

Parameters

Returns

IVaultPnl object with total PnL in native token and USD.

Get User Lifetime PnL

Calculate lifetime profit and loss for a user in a specific vault.

sdk.getVaultUserLifetimePnl({
  vault: string;
  wallet: string;
  chainId?: number;
}): Promise<IVaultUserLifetimePnl>

Parameters

Returns

IVaultUserLifetimePnl object with realized and unrealized PnL.

Get Yield Last Realized

Get the timestamp when yield was last realized for a vault.

sdk.getYieldLastRealizedOn({
  vault: string;
  chainId?: number;
}): Promise<number>

Parameters

Returns

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

Get Borrower Health Factor

Authentication is required for this function

Get the borrower's health factor by vault.

sdk.getVaultBorrowerHealthFactor({
  chainId?: number;
}): Promise<Record<string, number>>

Parameters

Returns

Object mapping vault addresses to their borrower health factors.

IVault Interface

All vault getter methods return the IVault interface:

Key Fields

depositAssets - Array of all supported deposit tokens including:

• Underlying asset (always first)
• Adapter tokens (if available)
• Whitelisted assets (for multi-asset vaults)

version - Determines which deposit/withdrawal functions to use:

• evm-0, evm-1: 2-param deposit
• evm-2: 3-param deposit with asset selection

position - User-specific data (when wallet provided):

• Wallet balance
• Available redemptions
• Pending redemptions
• Redeemable amount

Get User History

sdk.getUserHistory({
  wallet: string;
  chainId?: number;
  vault?: string;
}): Promise<IVaultUserHistoryItem[]>

Returns user transaction history (deposits, withdrawals, etc.).

Get User Transfers

sdk.getUserTransfers({
  wallet: string;
  chainId?: number;
  vault?: string;
}): Promise<IVaultTransfer[]>

Returns vault share transfer history for a user.

Get Staking Positions

sdk.getStakingPositions(
  wallet?: string,
  chainId?: number
): Promise<IActiveStakingPosition[]>

Returns active reward staking positions.

Examples

Complete Vault Query

const vault = await sdk.getVault({
  vault: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  chainId: 1,
  options: {
    loans: true,
    allocations: true,
    wallet: '0xYourWallet...',
  },
});

// Basic info
console.log(vault.name);
console.log(vault.version);
console.log(vault.apy.apy);

// Deposit options
console.log(
  'Can deposit:',
  vault.depositAssets.map((a) => a.symbol),
);

// User position
if (vault.position) {
  console.log('Your balance:', vault.position.walletBalance.normalized);
  console.log(
    'Available redemptions:',
    vault.position.availableRedemptions.length,
  );
}

// Loans (if available)
if (vault.loans) {
  console.log('Active loans:', vault.loans.length);
}

Filter Vaults by Criteria

const vaults = await sdk.getVaults();

// High APY vaults
const highYield = vaults.filter((v) => v.apy.apy > 10);

// Featured vaults
const featured = vaults.filter((v) => v.isFeatured);

// Active vaults only
const active = vaults.filter((v) => v.status === 'active');

// Vaults with deposits enabled
const depositable = vaults.filter((v) => !v.isDepositPaused);

// Multi-asset vaults
const multiAsset = vaults.filter((v) => v.version === 'evm-2');

Check Deposit Options

const vault = await sdk.getVault({
  vault: '0x5Fde59415625401278c4d41C6beFCe3790eb357f',
  chainId: 1,
});

// Show all deposit options to user
console.log('You can deposit:');
vault.depositAssets.forEach((asset) => {
  console.log(`- ${asset.symbol} (${asset.address})`);
});
// Output:
// - wstETH (0x7f39...)  <- Underlying
// - WETH (0xC02a...)    <- Adapter
// - ETH (0x0000...)     <- Adapter

Error Handling

try {
  const vault = await sdk.getVault({
    vault: vaultAddress,
    chainId: 1,
  });
} catch (error) {
  if (error.message.includes('Missing RPC URL')) {
    console.error('Configure RPC for this chain');
  } else if (error.message.includes('not found')) {
    console.error('Vault does not exist');
  } else {
    console.error('Failed to fetch vault:', error.message);
  }
}