> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK AI Coding Reference

> Condensed SDK reference optimized for AI coding assistants

Copy this page into your AI coding assistant (Cursor, Copilot, Claude, etc.) for accurate Amplify SDK completions.

<Info>
  This page is a condensed, single-file reference designed for AI context
  windows. For full documentation with interactive examples, see the [API
  Reference](/v0.5.2/intro/products/earn/developers/api/index).
</Info>

## Setup

```ts theme={null}
import { initAmplifySDK } from '@paxoslabs/amplify-sdk'

await initAmplifySDK('pxl_your_api_key', {
  rpcUrls: { 1: 'https://your-eth-rpc.com' }, // optional per-chain RPCs
  telemetry: { enabled: false }, // optional
  logLevel: 'DEBUG', // optional: DEBUG | INFO | WARN | ERROR
})
```

## Account Discovery (required before any transaction)

```ts theme={null}
import { getVaultsByConfig, YieldType } from '@paxoslabs/amplify-sdk'

// Find vaults by filters (all optional)
const vaults = await getVaultsByConfig({
  yieldType: YieldType.CORE, // CORE | TREASURY | FRONTIER
  chainId: 1, // EVM chain ID
  depositAssetAddress: '0x...', // token address
  withdrawAssetAddress: '0x...', // token address
  settlementAssetAddress: '0x...', // token address
})

const vault = vaults[0]
// vault.name   → string (used in all transaction functions)
// vault.chainId, vault.yieldType, vault.supportedAssets, vault.vault.address
```

## Deposit (unified API — recommended)

```ts theme={null}
import {
  prepareDepositAuthorization,
  prepareDeposit,
  isPermitAuth,
  isApprovalAuth,
  isAlreadyApprovedAuth,
} from '@paxoslabs/amplify-sdk'

// Step 1: Determine authorization method
const auth = await prepareDepositAuthorization({
  vaultName: vault.name, // string — from getVaultsByConfig()
  depositAsset: '0x...', // token address
  depositAmount: '1000', // human-readable string
  to: userAddress, // recipient address
  chainId: 1,
})

// Step 2: Handle based on method
if (isPermitAuth(auth)) {
  // auth.method === 'PERMIT'
  // auth.permitData — EIP-712 typed data for signing
  const signature = await walletClient.signTypedData(auth.permitData)
  const result = await prepareDeposit({ auth, signature })
  // result.txData — ready for walletClient.writeContract()
} else if (isApprovalAuth(auth)) {
  // auth.method === 'APPROVAL'
  // auth.txData — ERC-20 approve transaction
  await walletClient.writeContract(auth.txData)
  const result = await prepareDeposit({ auth })
  await walletClient.writeContract(result.txData)
} else if (isAlreadyApprovedAuth(auth)) {
  // auth.method === 'ALREADY_APPROVED'
  const result = await prepareDeposit({ auth })
  await walletClient.writeContract(result.txData)
}
```

## Withdrawal (unified API — recommended)

```ts theme={null}
import {
  prepareWithdrawalAuthorization,
  prepareWithdrawal,
  isWithdrawApprovalAuth,
  isWithdrawAlreadyApprovedAuth,
} from '@paxoslabs/amplify-sdk'

// Step 1: Check authorization
const auth = await prepareWithdrawalAuthorization({
  vaultName: vault.name,
  wantAsset: '0x...', // token to receive
  withdrawAmount: '500',
  userAddress: '0x...',
  chainId: 1,
})

// Step 2: Approve if needed, then withdraw
if (isWithdrawApprovalAuth(auth)) {
  await walletClient.writeContract(auth.txData)
}

const result = await prepareWithdrawal({
  vaultName: vault.name,
  wantAsset: '0x...',
  withdrawAmount: '500',
  userAddress: '0x...',
  chainId: 1,
})
await walletClient.writeContract(result.txData)
```

## Display Helpers

```ts theme={null}
import {
  getVaultAPY,
  getVaultTVL,
  getMinimumMint,
  getWithdrawalFee,
  getWithdrawalRequests,
  getMinimumWithdrawalOrderSize,
} from '@paxoslabs/amplify-sdk'

const apy = await getVaultAPY({ vaultName: vault.name })
// apy.apy → number (e.g., 5.25 for 5.25%)

const tvl = await getVaultTVL({ vaultName: vault.name, chainId: 1 })
// tvl.tvl → string (USD value)

const mint = await getMinimumMint({
  vaultName: vault.name,
  chainId: 1,
  depositAssetAddress: '0x...',
  depositAmount: '1000.0',
})
// mint.expectedShares → bigint

const fee = await getWithdrawalFee({
  vaultName: vault.name,
  chainId: 1,
  assetAddress: '0x...',
  amount: '500.0',
  offerAsset: '0x...', // share token address
  wantAsset: '0x...',  // withdrawal asset address
  receiver: '0x...',   // recipient address
})
// fee.feeAmount → bigint, fee.feePercentage → bigint

const { withdrawalRequests } = await getWithdrawalRequests({
  userAddress: '0x...',
  chainId: 1,
  status: 'PENDING', // optional filter
  vaultName: vault.name, // optional filter
})

const minSize = await getMinimumWithdrawalOrderSize({
  vaultName: vault.name,
  chainId: 1,
  assetAddress: '0x...',
})
// minSize.minimumOrderSize → bigint, minSize.shareDecimals → number
```

## Supported Assets

```ts theme={null}
import {
  getSupportedAssets,
  getWithdrawSupportedAssets,
} from '@paxoslabs/amplify-sdk'

// Deposit assets (all filters optional, combinable)
const assets = await getSupportedAssets({
  yieldType: YieldType.CORE,
  chains: [1, 8453],
  address: '0x...',
  symbol: 'USDC',
})
// assets[].address, .symbol, .name, .decimals, .coinGeckoTokenId, .chains

// Withdrawal assets grouped by token
const withdrawAssets = await getWithdrawSupportedAssets()
// withdrawAssets[].address, .symbol, .decimals, .vaults[]
```

## Cache Management

```ts theme={null}
import {
  initializeCache,
  getCache,
  refreshVaultCache,
  isCacheReady,
  waitForCacheReady,
} from '@paxoslabs/amplify-sdk'

initializeCache(300_000) // custom TTL in ms (default: 600_000)
await waitForCacheReady() // block until cache is populated
const ready = isCacheReady() // boolean check
await refreshVaultCache() // force refresh
const cache = getCache() // access cache instance
```

## Error Handling

```ts theme={null}
import { APIError, WithdrawError } from '@paxoslabs/amplify-sdk'

try {
  await prepareDeposit(params)
} catch (error) {
  if (error instanceof APIError) {
    console.error(error.message, error.endpoint, error.statusCode)
  }
  if (error instanceof WithdrawError) {
    console.error(error.message, error.vaultName, error.chainId)
  }
}
```

## Key Types

```ts theme={null}
interface AmplifyVault {
  id: string // unique vault config ID
  name: string // use as vaultName in all transaction functions
  chainId: number
  yieldType: 'CORE' | 'TREASURY' | 'FRONTIER'
  inDeprecation: boolean
  vault: VaultContracts // contract addresses
  enterpriseConfig?: { predicatePolicyId: string | null }
  sla?: VaultSLA
  supportedAssets: VaultSupportedAsset[]
}

interface VaultSupportedAsset {
  address: `0x${string}`
  symbol: string
  name: string
  decimals: number
  coinGeckoTokenId?: string
  depositable?: boolean
  withdrawable?: boolean
}

type YieldType = 'CORE' | 'TREASURY' | 'FRONTIER'
type DepositAuthMethod = 'PERMIT' | 'APPROVAL' | 'ALREADY_APPROVED'
type WithdrawAuthMethod = 'APPROVAL' | 'ALREADY_APPROVED'
```

## Supported Chains

Built-in `viem` chain configs (use these `chainId` values with the SDK):

| Chain          | ID       |
| -------------- | -------- |
| Ethereum       | 1        |
| Sepolia        | 11155111 |
| Base           | 8453     |
| HyperEVM       | 999      |
| Stable Testnet | 2201     |