Deposit Workflow - Paxos Labs

The unified deposit API simplifies deposits by automatically detecting the optimal authorization method. Use prepareDepositAuthorization() to determine the method, then prepareDeposit() to execute.

Breaking change in v0.5.0: All transaction functions identify accounts by vaultName: string instead of yieldType. Use getVaultsByConfig() or findVaultByConfig() to discover account names first. See the migration guide.

Import

import {
  prepareDepositAuthorization,
  prepareDeposit,
  getVaultsByConfig,
  isPermitAuth,
  isApprovalAuth,
  isAlreadyApprovedAuth,
  YieldType,
} from '@paxoslabs/amplify-sdk'

prepareDepositAuthorization()

Determines the optimal authorization method for a deposit operation.

Function Signature

async function prepareDepositAuthorization(
  params: PrepareDepositAuthorizationParams
): Promise<DepositAuthorizationResult>

Parameters

interface PrepareDepositAuthorizationParams {
  /** Human-readable vault name (from AmplifyVault.name) */
  vaultName: string

  /** Token contract address to deposit */
  depositAsset: Address

  /** Amount of assets to deposit as decimal string (e.g., "100.25") */
  depositAmount: string

  /** User's wallet address (permit owner / approval sender) */
  to: Address

  /** Blockchain network ID */
  chainId: number

  /** Optional deadline for permit signature (defaults to 1 hour from now) */
  deadline?: bigint

  /** Force specific authorization method (bypasses automatic detection) */
  forceMethod?: 'permit' | 'approval'
}

Parameter	Type	Required	Description
`vaultName`	`string`	Yes	Account name from `AmplifyVault.name` (e.g. from `getVaultsByConfig()`)
`depositAsset`	`Address`	Yes	Token contract address to deposit
`depositAmount`	`string`	Yes	Amount as decimal string (e.g., “100.25”)
`to`	`Address`	Yes	Recipient address for account shares
`chainId`	`number`	Yes	Blockchain network ID
`deadline`	`bigint`	No	Permit deadline (defaults to 1 hour)
`forceMethod`	`"permit" \| "approval"`	No	Override automatic detection

Return Type (Discriminated Union)

Type Definition
Permit Result
Approval Result
Already Approved Result

type DepositAuthorizationResult =
  | PermitAuthorizationResult
  | ApprovalAuthorizationResult
  | AlreadyApprovedAuthorizationResult;

/** Returned when token supports EIP-2612 permit */
interface PermitAuthorizationResult {
  method: "permit";
  /** EIP-712 typed data ready for wallet signing */
  permitData: PermitSignatureData;
}

/** Returned when an ERC20 approval transaction is needed */
interface ApprovalAuthorizationResult {
  method: "approval";
  /** Transaction data for ERC20 approve() call */
  txData: ApproveDepositTokenTxData;
}

/** Returned when existing allowance is sufficient */
interface AlreadyApprovedAuthorizationResult {
  method: "already_approved";
  /** Current allowance (human-readable) */
  allowance: string;
  /** Current allowance as BigInt string */
  allowanceAsBigInt: string;
}

Decision Logic

The function follows this priority order:

Check forceMethod — If specified, use that method directly
Detect smart wallet — If the address has deployed bytecode (Safe, EIP-4337, EIP-7702), route to APPROVAL so callers can batch approve + deposit atomically
Check permit support — If the token supports EIP-2612, return permit signature data
Check existing allowance — If sufficient, return ALREADY_APPROVED
Default to approval — Return approval transaction data

Token Permit Support

The following table shows which supported tokens use the gas-efficient EIP-2612 permit path versus the standard ERC-20 approval path. The SDK detects this automatically — use forceMethod: "approval" to override when needed (e.g., smart contract wallets).

Token	Authorization Method	Notes
USDC	Permit (EIP-2612)	Single-transaction gasless signature
USDG	Permit (EIP-2612)	Single-transaction gasless signature
pyUSD	Permit (EIP-2612)	Single-transaction gasless signature
USD₮0	Permit (EIP-2612)	Single-transaction gasless signature
USDT	Approval (ERC-20)	Requires separate approval transaction. Also requires resetting allowance to 0 before setting a new value when a non-zero allowance already exists.

prepareDeposit()

Prepares transaction data for a deposit, automatically using the correct method based on provided parameters.

Function Signature

async function prepareDeposit(
  params: PrepareDepositParams
): Promise<PrepareDepositResult>

Parameters

interface PrepareDepositParams {
  /** Human-readable vault name (from AmplifyVault.name) */
  vaultName: string

  /** Token contract address to deposit */
  depositAsset: Address

  /** Amount of assets to deposit as decimal string (e.g., "100.25") */
  depositAmount: string

  /** Recipient address for vault shares */
  to: Address

  /** Blockchain network ID */
  chainId: number

  /** Permit signature (required for permit flow) */
  signature?: Hex

  /** Permit deadline (required for permit flow) */
  deadline?: bigint

  /** Optional slippage in basis points (default: 50 = 0.5%) */
  slippage?: number

  /** Optional distributor code for fee attribution */
  distributorCode?: string

  /** Force deposit method (bypasses automatic routing) */
  forceMethod?: 'permit' | 'approval'
}

Return Type

Returns a discriminated union based on which deposit method is used:

/** Standard deposit (after approval or when already approved) */
interface StandardDepositResult {
  method: 'approval'
  txData: DepositTxData // flat: { abi, address, functionName, args, chainId }
}

/** Permit deposit (with signature) */
interface PermitDepositResult {
  method: 'permit'
  txData: UnencodedDepositWithPermitData // flat: { depositType, abi, address, functionName, args, chainId }
}

type PrepareDepositResult = StandardDepositResult | PermitDepositResult

Both result variants have the same flat txData shape — txData.abi, txData.address, txData.functionName, txData.args, txData.chainId. You can spread txData directly into viem’s writeContract regardless of method.

Complete Flow Example

import { mainnet } from 'viem/chains'
import {
  getVaultsByConfig,
  prepareDepositAuthorization,
  prepareDeposit,
  isPermitAuth,
  isApprovalAuth,
  isAlreadyApprovedAuth,
  YieldType,
} from '@paxoslabs/amplify-sdk'

const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' as `0x${string}`

// Step 0: Discover the vault to get its name
const [vault] = await getVaultsByConfig({
  yieldType: YieldType.CORE,
  chainId: mainnet.id,
  depositAssetAddress: USDC,
})

const params = {
  vaultName: vault.name,
  depositAsset: USDC,
  depositAmount: '1000',
  to: userAddress,
  chainId: mainnet.id,
}

// Step 1: Get authorization method
const auth = await prepareDepositAuthorization(params)

// Step 2: Handle based on method using type guards
if (isPermitAuth(auth)) {
  // Sign permit off-chain
  const signature = await walletClient.signTypedData({
    account: userAddress,
    ...auth.permitData,
  })

  // Prepare and execute deposit with permit
  const prepared = await prepareDeposit({
    ...params,
    signature,
    deadline: auth.permitData.message.deadline,
  })

  await walletClient.writeContract({
    ...prepared.txData,
    account: userAddress,
  })
} else if (isApprovalAuth(auth)) {
  // Execute approval first
  const approvalHash = await walletClient.writeContract(auth.txData)
  await publicClient.waitForTransactionReceipt({ hash: approvalHash })

  // Then deposit (standard path: txData is flat)
  const prepared = await prepareDeposit(params)
  await walletClient.writeContract(prepared.txData)
} else if (isAlreadyApprovedAuth(auth)) {
  // Deposit directly (standard path: txData is flat)
  const prepared = await prepareDeposit(params)
  await walletClient.writeContract(prepared.txData)
}

Force Specific Method

Override automatic detection when needed:

// Force permit even if automatic detection would choose approval
const authForcePermit = await prepareDepositAuthorization({
  ...params,
  forceMethod: 'permit',
})

// Force approval even for permit-supporting tokens (useful for smart wallets)
const authForceApproval = await prepareDepositAuthorization({
  ...params,
  forceMethod: 'approval',
})

Slippage Configuration

const prepared = await prepareDeposit({
  ...params,
  slippage: 100, // 1% instead of default 0.5%
})

Error Handling

Error Message Pattern	Description	Resolution
`"SDK not initialized"`	SDK used before init	Call `initAmplifySDK()` first
`"Vault not found"`	No account matches `vaultName`	Verify account name via `getVaultsByConfig()`
`"does not support EIP-2612 permit"`	Token doesn’t support permits	Use approval flow instead
`"requires both signature and deadline"`	Missing permit params	Provide signature and deadline for permit deposits

getVaultsByConfig - Discover account names
Deposits Guide - Complete integration examples
DepositAuthMethod - Type definitions
prepareDepositTxData - Lower-level deposit function

​Import

​prepareDepositAuthorization()

​Function Signature

​Parameters

​Return Type (Discriminated Union)

​Decision Logic

​Token Permit Support

​prepareDeposit()

​Function Signature

​Parameters

​Return Type

​Complete Flow Example

​Force Specific Method

​Slippage Configuration

​Error Handling

​Related

Import

prepareDepositAuthorization()

Function Signature

Parameters

Return Type (Discriminated Union)

Decision Logic

Token Permit Support

prepareDeposit()

Function Signature

Parameters

Return Type

Complete Flow Example

Force Specific Method

Slippage Configuration

Error Handling

Related