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

> Initialize the Amplify SDK with your API key before using any functions

All Amplify SDK functions require initialization before use. Call `initAmplifySDK()` once at application startup.

## initAmplifySDK()

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

await initAmplifySDK("pxl_your_api_key");
```

### Function Signature

```ts theme={null}
export async function initAmplifySDK(
  apiKey: string,
  options?: SDKInitOptions
): Promise<void>;
```

### Parameters

| Parameter | Type             | Required | Description                                     |
| --------- | ---------------- | -------- | ----------------------------------------------- |
| `apiKey`  | `string`         | Yes      | Your Paxos Labs API key (format: `pxl_...`)     |
| `options` | `SDKInitOptions` | No       | Configuration options for telemetry and logging |

### SDKInitOptions

```ts theme={null}
export interface SDKInitOptions {
  /** Enable/disable PostHog telemetry (default: true) */
  telemetry?: boolean;

  /** Log level for SDK operations (default: LogLevel.ERROR) */
  logLevel?: LogLevel;

  /** Custom logger implementation */
  logger?: Logger;
}
```

| Option      | Type       | Default                 | Description                   |
| ----------- | ---------- | ----------------------- | ----------------------------- |
| `telemetry` | `boolean`  | `true`                  | Enable PostHog error tracking |
| `logLevel`  | `LogLevel` | `LogLevel.ERROR`        | Minimum log level to output   |
| `logger`    | `Logger`   | Built-in console logger | Custom logger implementation  |

## Usage Examples

### Basic Initialization

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

// Initialize with just the API key
await initAmplifySDK("pxl_your_api_key");
```

### With Telemetry Disabled

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

await initAmplifySDK("pxl_your_api_key", {
  telemetry: false,
});
```

### With Debug Logging

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

await initAmplifySDK("pxl_your_api_key", {
  logLevel: LogLevel.DEBUG,
});
```

### With All Options

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

await initAmplifySDK("pxl_your_api_key", {
  telemetry: false,
  logLevel: LogLevel.DEBUG,
  logger: {
    debug: (msg, ctx) => console.debug(`[SDK] ${msg}`, ctx),
    info: (msg, ctx) => console.info(`[SDK] ${msg}`, ctx),
    warn: (msg, ctx) => console.warn(`[SDK] ${msg}`, ctx),
    error: (msg, ctx) => console.error(`[SDK] ${msg}`, ctx),
  },
});
```

## React Integration

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

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

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);
        initialized = true;
        setIsReady(true);
      } catch (err) {
        setError(err instanceof Error ? err : new Error("SDK initialization failed"));
      }
    }

    init();
  }, []);

  return { isReady, error };
}
```

Call the hook near the root of your app:

```tsx theme={null}
// src/App.tsx
import { useAmplify } from "./hooks/useAmplify";

export function App() {
  const { isReady, error } = useAmplify();

  if (error) {
    return <div>Failed to initialize SDK: {error.message}</div>;
  }

  if (!isReady) {
    return <div>Initializing...</div>;
  }

  return <YourApp />;
}
```

## Behavior

* **Validates API key** - Ensures key follows expected format
* **Pre-populates cache** - Fetches vaults and assets during initialization
* **Configures telemetry** - Sets up PostHog if enabled
* **Configures logging** - Sets log level and optional custom logger
* **Idempotent** - Multiple calls with same key are no-ops
* **Re-initialization** - Different key clears cache and reconfigures

## Error Handling

```ts theme={null}
try {
  await initAmplifySDK("pxl_your_api_key");
} catch (error) {
  if (error.code === "INVALID_API_KEY") {
    console.error("Invalid API key format");
  }
}
```

| Error Code            | Description                        | Resolution                    |
| --------------------- | ---------------------------------- | ----------------------------- |
| `SDK_NOT_INITIALIZED` | SDK used before `initAmplifySDK()` | Call `initAmplifySDK()` first |
| `INVALID_API_KEY`     | API key validation failed          | Check API key format          |

For advanced logging configuration, see [Logging](./logging).