Skip to main content
Before wiring calldata into your product, align on how Amplify Earn models strategies, assets, and execution responsibilities. These concepts shape the SDK helpers referenced throughout the docs.

​
Vaults & Vault Names

  • Vault – On-chain contract that issues ERC-20 shares representing a position in an underlying strategy.
  • Vault Name – A human-readable string identifier (AmplifyVault.name) used to address a specific vault in all transaction functions. Call getVaultsByConfig() to discover vault names.
  • Yield Type – Logical grouping of vaults with similar mandates, exposed as the YieldType enum (CORE, TREASURY, FRONTIER). Used as a filter when discovering vaults, not as a transaction parameter.
  • Want Asset – Token users receive when withdrawing from a vault; often different from the deposit token.

​
Vault Discovery Pattern

import { getVaultsByConfig } from '@paxoslabs/amplify-sdk'

// Step 1: Discover vaults (use chainId as a filter)
const [vault] = await getVaultsByConfig({
  chainId: 1,
  depositAssetAddress: USDC_ADDRESS,
})

// Step 2: Use vault.name in all transaction functions
console.log(vault.name) // e.g. "amplify-core-eth-usdc"
Use getSupportedAssets() to discover eligible deposit tokens and chain IDs.

​
Shares vs. Assets

  • Deposits mint shares to the recipient. Shares track ownership of the vault.
  • Withdrawals burn shares and return the want asset using prepareWithdrawal.
  • Helpers return base-unit values; you provide the human-readable amounts as decimal strings.

​
Allowances vs. Permits

  • Unified API (Recommended): Use prepareDepositAuthorization() to automatically detect the optimal method. It returns the appropriate flow based on token support and existing allowances.
  • Approval flow: Traditional ERC20 approval using prepareApproveDepositTokenTxData() followed by prepareDepositTxData().
  • Permit flow: When the token supports EIP-2612, sign typed data off-chain and use prepareDepositWithPermitTxData() for gas-efficient single-transaction deposits.
The unified API handles method detection automatically—use it for the best developer experience.

​
Slippage Controls

  • Slippage is expressed in basis points (bps). For example, 100 means 1%.
  • Deposit helpers default to 50 bps (0.5%).
  • WithdrawQueue-based withdrawals do not require slippage or deadline parameters.
  • Helpers return minimum acceptable amounts in base units; you can override or disable slippage (not recommended for production).

​
Execution Responsibilities

  • The SDK prepares calldata only; your app decides which signing stack executes it.
  • Use viem, wagmi, Privy, or custody flows to send the transaction.
  • Handle errors by catching APIError, which includes an endpoint property (e.g., prepareDepositWithPermitTxData).

​
Withdrawals

  • Use prepareWithdrawalAuthorization to determine whether approval is required.
  • Use prepareWithdrawal to build the withdrawal order transaction.
  • For lower-level control, use prepareWithdrawOrderTxData and prepareApproveWithdrawOrderTxData.

​
Cache & Initialization

The SDK caches vault and asset data on startup. For guaranteed fast first calls: 
import { initAmplifySDK, waitForCacheReady } from '@paxoslabs/amplify-sdk'

await initAmplifySDK('pxl_your_api_key')
await waitForCacheReady() // Optional: ensures cache is ready before first call
Without waitForCacheReady(), the first call that needs vault data will trigger a cache refresh automatically. Keep these concepts in mind while following the Quickstart or diving into the API Reference.