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

# Installation & Setup

> Install the Amplify SDK, configure your project, and initialize

## Requirements

* Node.js 22 or higher
* npm, yarn, pnpm, or bun

## Install the SDK

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @paxoslabs/amplify-sdk
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @paxoslabs/amplify-sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @paxoslabs/amplify-sdk
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add @paxoslabs/amplify-sdk
    ```
  </Tab>
</Tabs>

## Install Peer Dependencies

The SDK works with various wallet libraries. Install the dependencies for your chosen stack:

<Tabs>
  <Tab title="Privy">
    ```bash theme={null}
    pnpm add @privy-io/react-auth viem @tanstack/react-query
    ```
  </Tab>

  <Tab title="Wagmi">
    ```bash theme={null}
    pnpm add wagmi viem @tanstack/react-query
    ```
  </Tab>

  <Tab title="Viem Only">
    ```bash theme={null}
    pnpm add viem
    ```
  </Tab>
</Tabs>

## Environment Variables

Create `.env.local` (ignored by Vite by default):

```bash theme={null}
# Required
VITE_AMPLIFY_API_KEY=pxl_your_api_key

# Optional: Wallet provider credentials
VITE_PRIVY_APP_ID=your-privy-app-id

# Recommended: Custom RPC endpoints
VITE_APP_ETHEREUM_MAINNET_RPC=https://eth-mainnet.g.alchemy.com/v2/your-key
VITE_APP_ETHEREUM_SEPOLIA_RPC=https://eth-sepolia.g.alchemy.com/v2/your-key
```

<Warning>
  Never commit `.env.local`. Provide an `.env.example` without secrets for teammates.
</Warning>

## Initialize the SDK

Call `initAmplifySDK()` once at application startup before using any other SDK functions.

### Basic

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

await initAmplifySDK("pxl_your_api_key");
```

### With Custom RPCs

For the best user experience and reliability, use your own RPC endpoints:

```ts theme={null}
import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
import { mainnet, sepolia } from "viem/chains";

await initAmplifySDK("pxl_your_api_key", {
  rpcUrls: {
    [mainnet.id]: import.meta.env.VITE_APP_ETHEREUM_MAINNET_RPC,
    [sepolia.id]: import.meta.env.VITE_APP_ETHEREUM_SEPOLIA_RPC,
  },
});
```

### With All Options

```ts theme={null}
import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";

await initAmplifySDK("pxl_your_api_key", {
  rpcUrls: {
    1: import.meta.env.VITE_APP_ETHEREUM_MAINNET_RPC,
  },
  telemetry: true,
  logLevel: LogLevel.ERROR,
});
```

### React Integration Hook

Create a hook to initialize the SDK once and expose ready state:

```ts theme={null}
// src/hooks/useAmplify.ts
import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";
import { useEffect, useState } from "react";
import { mainnet } from "viem/chains";

let initialized = false;

export function useAmplify() {
  const [isReady, setIsReady] = useState(initialized);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    if (initialized) {
      setIsReady(true);
      return;
    }

    const apiKey = import.meta.env.VITE_AMPLIFY_API_KEY;
    if (!apiKey) {
      setError(new Error("Missing VITE_AMPLIFY_API_KEY env variable"));
      return;
    }

    async function init() {
      try {
        await initAmplifySDK(apiKey, {
          rpcUrls: {
            [mainnet.id]: import.meta.env.VITE_APP_ETHEREUM_MAINNET_RPC,
          },
          logLevel: LogLevel.ERROR,
          telemetry: true,
        });
        initialized = true;
        setIsReady(true);
      } catch (err) {
        setError(err instanceof Error ? err : new Error("SDK initialization failed"));
      }
    }

    init();
  }, []);

  return { isReady, error };
}
```

## Verify Installation

Test that everything is working:

```ts theme={null}
import { initAmplifySDK, getVaultsByConfig } from "@paxoslabs/amplify-sdk";

async function verify() {
  await initAmplifySDK("pxl_your_api_key");

  const vaults = await getVaultsByConfig();
  console.log(`Found ${vaults.length} vaults:`);
  for (const vault of vaults) {
    console.log(`  ${vault.name} — ${vault.yieldType} on chain ${vault.chainId}`);
  }
}

verify();
```

## Package Exports

The SDK supports focused imports for tree-shaking:

```ts theme={null}
// Main entry — all public APIs
import { initAmplifySDK, getVaultsByConfig } from "@paxoslabs/amplify-sdk";

// Low-level helpers (contract reads, price feeds)
import { getEthPrice, getRateInQuoteWithAssetDecimals } from "@paxoslabs/amplify-sdk/core";

// Vault operations
import { prepareDeposit, prepareDepositAuthorization } from "@paxoslabs/amplify-sdk/vaults";

// Utility helpers
import { calculateDeadline } from "@paxoslabs/amplify-sdk/utils";
```

## Global Providers

Set up React Query and your wallet provider:

```tsx theme={null}
// src/app/providers.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { PrivyProvider } from "@privy-io/react-auth";
import type { ReactNode } from "react";

const queryClient = new QueryClient();

export function AmplifyProviders({ children }: { children: ReactNode }) {
  if (!import.meta.env.VITE_PRIVY_APP_ID) {
    throw new Error("Missing VITE_PRIVY_APP_ID env variable");
  }

  return (
    <PrivyProvider appId={import.meta.env.VITE_PRIVY_APP_ID}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </PrivyProvider>
  );
}
```

Wire the providers in your entry point:

```tsx theme={null}
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import { AmplifyProviders } from "./providers.tsx";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <AmplifyProviders>
      <App />
    </AmplifyProviders>
  </StrictMode>,
);
```

## Recommended Directory Structure

<Tree>
  <Tree.File name=".env.local" />

  <Tree.File name="package.json" />

  <Tree.Folder name="src" defaultOpen>
    <Tree.Folder name="app" defaultOpen>
      <Tree.File name="App.tsx" />

      <Tree.File name="providers.tsx" />
    </Tree.Folder>

    <Tree.Folder name="components" defaultOpen>
      <Tree.File name="DepositForm.tsx" />

      <Tree.File name="WithdrawForm.tsx" />
    </Tree.Folder>

    <Tree.Folder name="hooks" defaultOpen>
      <Tree.File name="useAmplify.ts" />

      <Tree.File name="useBalances.ts" />
    </Tree.Folder>

    <Tree.Folder name="lib" defaultOpen>
      <Tree.File name="privy.ts" />

      <Tree.File name="viem.ts" />
    </Tree.Folder>

    <Tree.Folder name="pages" />

    <Tree.Folder name="styles" />

    <Tree.File name="main.tsx" />
  </Tree.Folder>
</Tree>

| Layer          | Directory               | Purpose                                                                                  |
| -------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
| **Providers**  | `src/app/providers.tsx` | Initialize Privy, React Query, and the Amplify SDK once.                                 |
| **Hooks**      | `src/hooks/`            | Wrap SDK helpers with domain-specific logic and query invalidation.                      |
| **Components** | `src/components/`       | Pure UI components that receive prepared data plus callbacks for execution.              |
| **Lib**        | `src/lib/`              | Interaction helpers for viem, Privy, or analytics that should not depend on React state. |

## Server-Side Usage

If you execute transactions from a backend service, mirror the same separation:

* `server/app.ts` – Express/Fastify entry point
* `server/clients/amplify.ts` – `initAmplifySDK` and helper wrappers
* `server/services/deposits.ts` – orchestrates approvals, permits, or withdrawals

## Next Steps

* Follow the [Deposits guide](./deposits) to implement your first deposit flow
* See [initAmplifySDK](/v0.5.2/intro/products/earn/developers/api/initAmplifySDK) for full API reference
* Check [Logging](./logging) for debug configuration