> ## 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.

# Concepts

> Key ideas to understand before integrating Amplify Earn

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.

## Accounts & Account Names

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

### Account Discovery Pattern

```ts theme={null}
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 account.
* 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](https://eips.ethereum.org/EIPS/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 account and asset data on startup. For guaranteed fast first calls:

```ts theme={null}
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 account data will trigger a cache refresh automatically.

***

## Glossary

| Term                   | Definition                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Approval**           | An on-chain transaction granting a contract permission to transfer your tokens                             |
| **Basis points (bps)** | A unit of measurement where 1 bps = 0.01%. 50 bps = 0.5%, 100 bps = 1%.                                    |
| **EIP-2612 Permit**    | An off-chain signature that authorizes token spending without an on-chain approval transaction             |
| **ERC-20**             | The standard interface for fungible tokens (USDC, USDT, etc.)                                              |
| **Gas**                | The fee paid in ETH to execute a transaction on Ethereum                                                   |
| **Slippage**           | The difference between the expected and actual exchange rate. Controlled via `slippageBps`.                |
| **Account shares**     | ERC-20 tokens representing your deposit in the account; their value appreciates as the account earns yield |
| **Want asset**         | The token you want to receive when withdrawing (e.g., USDC)                                                |
| **Yield Type**         | Logical grouping of accounts (`CORE`, `TREASURY`, `FRONTIER`) used as a filter in account discovery        |

Keep these concepts in mind while following the [Quickstart](./quickstart) or diving into the [API Reference](/v0.5.2/intro/products/earn/developers/api/index).