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

# Developer Guide

> End-to-end workflow for shipping Amplify Earn features

This guide walks through the lifecycle of launching and maintaining a Stablecoin Earn integration—from sandbox setup to production operations. Treat it as the map that connects the [Quickstart](./quickstart), [Concepts](./concepts), and [Functions](./functions/index) sections.

## 1. Access & Environment

1. Request a Paxos-issued Amplify **API key** for your environment (sandbox, staging, production).
2. Store the key as a secret (`.env`, HashiCorp Vault, CI secrets manager).
3. Confirm network access to required RPC endpoints (Alchemy, Infura, or your in-house nodes).
4. Decide where transactions are signed (end-user wallet via Privy, custodial flow, or backend signer).

## 2. Scaffold the App

* Follow the [Quickstart](./quickstart) to spin up a Vite + React + Privy project.
* Mirror the recommended [Directory Structure](./directory-structure) and create providers for Privy, Amplify, and your data cache.
* Add feature flags or progressive rollout gates if you are staging Earn access.

## 3. Initialize the SDK

* Call `initAmplifySDK(apiKey)` once on boot (client or server).
* Wrap the call in a provider that throws if the key is missing or the init step fails.
* Track initialization metrics to catch missing environment variables early.

## 4. Discover Vaults & Assets

* Use `fetchSupportedAssets` to build product selectors.

```ts theme={null}
// App.tsx

import {
  fetchSupportedAssets,
  initAmplifySDK,
  YieldType,
  type SupportedAsset,
} from "@paxoslabs/amplify-sdk";

// Initialize sdk with your PaxosLabs API key
initAmplifySDK(import.meta.env.VITE_APP_PAXOS_API_KEY as string);

// Fetch supported assets based on the specific YieldType
// Note: the example given is using TanStack Query
const {
  data: sdkAssets,
  isLoading: isLoadingSdkAssets,
  isError: isErrorSdkAssets,
} = useQuery({
  queryKey: ["amplifySDK"], // query key is part of TanStack Query and can be anything.
  queryFn: () => fetchSupportedAssets({ yieldType: YieldType.PRIME }),
});
```

* Cache results (React Query, SWR, server-side caches) with sensible revalidation periods.
* Map vault metadata to your UI components (APY, supported assets, min/max).

## 5. Execute Flows

Our focus is on trying to provide the best UX possible for our users. Because of this you may notice multiple functions that appear to have similar functionality.

**Standard Approve vs. Permit Transactions**

On most blockchains, smart contracts cannot move your tokens without explicit permission. The traditional approach requires two separate transactions: first, you send an "approve" transaction that grants a specific contract permission to spend a certain amount of your tokens, then you send a second transaction to actually perform the deposit or transfer. Each transaction costs gas fees and requires user confirmation. EIP-2612 introduced "permit"—a more elegant alternative where you sign a message (off-chain, with no gas cost) that authorizes the contract, and then submit a single transaction that includes both the permission and the action. This reduces friction from two on-chain transactions to one, cutting gas costs in half and streamlining the user experience. Not all tokens support permit, so your application should check asset compatibility and fall back to the approve flow when necessary.

Our recommendation is to use `prepareDepositWithPermitTransactionData`. However, not all Tokens support this functionality or this may not align to your business needs. Because of this we provide additional options to ensure we can support your needs.

| Flow              | Primary Helpers                                                   | Notes                                                   |
| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Approve & Deposit | `prepareApproveDepositTokenTxData`, `prepareDepositTxData`        | Use when ERC-20 approval is required.                   |
| Permit Deposit    | `prepareDepositPermitSignature`, `prepareDepositWithPermitTxData` | Skip approvals when asset supports EIP-2612.            |
| Withdraw          | `prepareApproveWithdrawTxData`, `prepareWithdrawTxData`           | Burns shares and returns want token in one transaction. |

* Each helper returns deterministic calldata and throws `APIError` with actionable metadata.
* Execute transactions with `viem`, `wagmi`, or Privy helpers—never with raw `ethers.js` strings.
* Record failed transactions alongside the `endpoint` value to accelerate debugging.

You now have the skeleton needed to build durable Earn experiences. Dive into the [Concepts](./concepts) section for protocol context or jump back to the [Quickstart](./quickstart) when onboarding new teammates.\*\*\*