<div align="center">

# Paxos Labs Amplify SDK

**Official TypeScript SDK for the Paxos Labs Amplify API** — vault discovery, deposits, withdrawals, and user positions.

[![npm version](https://img.shields.io/npm/v/@paxoslabs/amplify-sdk.svg?color=2ea043&label=npm)](https://www.npmjs.com/package/@paxoslabs/amplify-sdk)
[![npm downloads](https://img.shields.io/npm/dm/@paxoslabs/amplify-sdk.svg?color=2ea043)](https://www.npmjs.com/package/@paxoslabs/amplify-sdk)
[![types](https://img.shields.io/npm/types/@paxoslabs/amplify-sdk.svg?color=3178c6)](https://www.typescriptlang.org)
[![license](https://img.shields.io/npm/l/@paxoslabs/amplify-sdk.svg?color=blue)](./LICENSE)

[Documentation](https://developers.paxoslabs.com) · [API Reference](https://developers.paxoslabs.com) · [Changelog](./CHANGELOG.md)

</div>

---

Generated from the Amplify OpenAPI specification, so every method, type, and error is fully typed and stays in lockstep with the API.

## Table of contents

- [Installation](#installation)
- [Quickstart](#quickstart)
- [Configuration](#configuration)
- [Resources](#resources)
- [Error handling](#error-handling)
- [Types](#types)
- [License](#license)

## Installation

```bash
npm install @paxoslabs/amplify-sdk
# pnpm add @paxoslabs/amplify-sdk
# yarn add @paxoslabs/amplify-sdk
# bun add @paxoslabs/amplify-sdk
```

> Requires Node.js **>= 24**.

## Quickstart

```ts
import { AmplifyClient } from '@paxoslabs/amplify-sdk'

const client = new AmplifyClient({ apiKey: process.env.PAXOS_LABS_API_KEY! })

const { vaults } = await client.amplify.vaults.list({ filter: 'chainId=1' })
```

The API key is sent as the `x-api-key` header and authenticates every request.

> [!IMPORTANT]
> **Keep your API key server-side.** It must never ship to the browser. Call the SDK from a backend (Route Handler, Server Action, or API server), return the prepared transaction payload, and sign it client-side with the user's wallet.

## Configuration

```ts
interface AmplifyClientOptions {
  /** API key (required). Sent as the `x-api-key` header on every request. */
  apiKey: string
  /** Environment override. Defaults to production. */
  environment?: string
  /** Base URL override. Takes precedence over `environment`. */
  baseUrl?: string
}
```

The client targets the production API by default; pass `environment` or `baseUrl` only for non-production use.

## Resources

Each API area is exposed as a subclient on the `AmplifyClient` instance.

| Accessor | Purpose |
| :--- | :--- |
| `client.amplify.vaults` | List vaults and assets; fetch APYs, TVLs, compositions, supply caps, and liquidity shortfalls |
| `client.amplify.deposit` | Prepare deposit transactions |
| `client.amplify.smartDeposits` | Create a smart deposit address for a user |
| `client.amplify.withdraw` | Prepare (`prepare`) and cancel (`cancel`) withdrawals; calculate fees (`calculateFee`); list requests (`listRequests`) and volumes (`getVolumes`) |
| `client.amplify.users` | Fetch user positions |
| `client.core.authorization` | Detect (`detect`) token authorization requirements (permit, approval, or already approved) |

### Example: prepare a deposit

```ts
const prepared = await client.amplify.deposit.prepare({
  vaultAddress,
  depositAsset,
  depositAmount,
  userAddress,
  chainId,
})

// prepared.transaction → { to, data, value }
// Sign and broadcast it with the user's wallet (viem / wagmi / Privy / Dynamic).
```

### Example: create a smart deposit address

```ts
const { smartDepositAddress } = await client.amplify.smartDeposits.getAddress({
  userDestinationAddress,
  vaultAddress,
  inputToken,
  chainId,
})
```

## Error handling

Requests reject with `AmplifyError` (carrying `statusCode` and `message`); requests that exceed the timeout reject with `AmplifyTimeoutError`.

```ts
import { AmplifyError } from '@paxoslabs/amplify-sdk'

try {
  await client.amplify.deposit.prepare(request)
} catch (err) {
  if (err instanceof AmplifyError) {
    console.error(err.statusCode, err.message)
  }
  throw err
}
```

## Types

Generated types are available under the `Amplify` namespace:

```ts
import { Amplify } from '@paxoslabs/amplify-sdk'

// Response types are at the top level
type DepositResponse = Amplify.PrepareDepositResponseDto
type AuthResponse = Amplify.AuthorizationResponseDto

// Request types are nested under resource namespaces
type DepositRequest = Amplify.amplify.deposit.PrepareDepositRequest
type AuthRequest = Amplify.core.authorization.DetectAuthorizationRequest
```

## License

[BSD-3-Clause](./LICENSE) © Paxos Labs