@paxoslabs/amplify-sdk 0.5.3 → 1.0.1

package/LICENSE

@@ -25,4 +25,4 @@ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,119 +1,141 @@
-```
-   _____                 .__  .__  _____          _________________   ____  __.
-  /  _  \   _____ ______ |  | |__|/ ____\__.__.  /   _____/\______ \ |    |/ _|
- /  /_\  \ /     \\____ \|  | |  \   __<   |  |  \_____  \  |    |  \|      <
-/    |    \  Y Y  \  |_> >  |_|  ||  |  \___  |  /        \ |    `   \    |  \
-\____|__  /__|_|  /   __/|____/__||__|  / ____| /_______  //_______  /____|__ \
-        \/      \/|__|                  \/              \/         \/        \/
-```
+<div align="center">
 
 # Paxos Labs Amplify SDK
 
-A TypeScript SDK for interacting with Paxos Labs Amplify Vaults, providing type-safe functions for discovering vaults, depositing assets, and withdrawing across multiple blockchain networks.
+**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)
 
-[![npm version](https://img.shields.io/npm/v/@paxoslabs/amplify-sdk.svg)](https://www.npmjs.com/package/@paxoslabs/amplify-sdk)
-[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[Documentation](https://developers.paxoslabs.com) · [API Reference](https://developers.paxoslabs.com) · [Changelog](./CHANGELOG.md)
 
-## Features
+</div>
+
+---
 
-- **Vault Discovery** - Query available vaults and supported assets via API
-- **Deposits** - Deposit assets into vaults with slippage protection
-- **Withdrawals** - Withdraw assets from vaults with deadline protection
-- **Permit Deposits** - Gas-optimized deposits using EIP-2612 permit signatures
-- **Cache Management** - Optimize API calls with built-in caching
-- **Multi-Chain Support** - Seamless operations across 7+ blockchain networks
-- **Full TypeScript Support** - Complete type definitions and autocomplete
-- **React Ready** - Works with viem (vanilla) and wagmi (React hooks)
+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
-npm install @paxoslabs/amplify-sdk viem
+npm install @paxoslabs/amplify-sdk
+# pnpm add @paxoslabs/amplify-sdk
+# yarn add @paxoslabs/amplify-sdk
+# bun add @paxoslabs/amplify-sdk
+```
+
+> Requires Node.js **>= 24**.
 
-# yarn
-yarn add @paxoslabs/amplify-sdk viem
+## Quickstart
 
-# pnpm
-pnpm add @paxoslabs/amplify-sdk viem
+```ts
+import { AmplifyClient } from '@paxoslabs/amplify-sdk'
 
-# For React apps, also install wagmi
-pnpm add wagmi @tanstack/react-query
+const client = new AmplifyClient({ apiKey: process.env.PAXOS_LABS_API_KEY! })
+
+const { vaults } = await client.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
+}
 ```
 
-## Quick Start
-
-```typescript
-import {
-  initAmplifySDK,
-  prepareDepositAuthorization,
-  prepareDeposit,
-  DepositAuthMethod,
-} from '@paxoslabs/amplify-sdk'
-
-// Initialize SDK with your API key
-await initAmplifySDK('pxl_your_api_key')
-
-// Or initialize with custom RPC URLs for better reliability
-await initAmplifySDK('pxl_your_api_key', {
-  rpcUrls: {
-    1: 'https://my-eth-rpc.com', // Ethereum
-    999: 'https://my-hyperEVM-rpc.com', // HyperEVM
-  },
+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.vaults` | List vaults and assets; fetch APYs, TVLs, compositions, supply caps, and liquidity shortfalls |
+| `client.deposit` | Prepare deposit transactions |
+| `client.smartDeposits` | Create a smart deposit address for a user |
+| `client.withdraw` | Prepare and cancel withdrawals; calculate fees; list requests and volumes |
+| `client.users` | Fetch user positions |
+| `client.permit` | ERC-20 permit / authorization detection |
+
+### Example: prepare a deposit
+
+```ts
+const prepared = await client.deposit.prepareDeposit({
+  vaultAddress,
+  depositAsset,
+  depositAmount,
+  userAddress,
+  chainId,
 })
 
-// Prepare deposit authorization (auto-detects permit vs approval)
-const auth = await prepareDepositAuthorization({
-  yieldType: 'CORE',
-  depositAsset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
-  depositAmount: '1000.0',
-  to: userAddress,
-  chainId: 1,
+// 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.smartDeposits.getAddress({
+  userDestinationAddress,
+  vaultAddress,
+  inputToken,
+  chainId,
 })
+```
 
-// Shared deposit parameters
-const depositParams = {
-  yieldType: 'CORE',
-  depositAsset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
-  depositAmount: '1000.0',
-  to: userAddress,
-  chainId: 1,
-}
+## Error handling
 
-// Handle based on authorization method
-if (auth.method === DepositAuthMethod.PERMIT) {
-  // Token supports EIP-2612: sign permit and deposit in one transaction
-  const signature = await signTypedData(auth.permitData)
-  const tx = await prepareDeposit({
-    ...depositParams,
-    signature,
-    deadline: auth.permitData.message.deadline,
-  })
-  await writeContract(tx.txData)
-} else if (auth.method === DepositAuthMethod.APPROVAL) {
-  // Token requires ERC20 approval: approve first, then deposit
-  await writeContract(auth.txData)
-  const tx = await prepareDeposit(depositParams)
-  await writeContract(tx.txData)
-} else if (auth.method === DepositAuthMethod.ALREADY_APPROVED) {
-  // Sufficient allowance exists: proceed directly to deposit
-  const tx = await prepareDeposit(depositParams)
-  await writeContract(tx.txData)
+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.deposit.prepareDeposit(request)
+} catch (err) {
+  if (err instanceof AmplifyError) {
+    console.error(err.statusCode, err.message)
+  }
+  throw err
 }
 ```
 
-## Documentation
+## Types
 
-Full documentation at https://developers.paxoslabs.com/
-
-## License
+Generated request and response types are available under the `Amplify` namespace:
 
-BSD © Paxos Labs
+```ts
+import { Amplify } from '@paxoslabs/amplify-sdk'
 
----
+const request: Amplify.PrepareDepositRequest = {
+  /* ... */
+}
+```
 
-**Need Help?**
+## License
 
-- 📖 [Full Documentation](./docs/getting-started.mdx)
-- 🐛 [Report Issues](https://github.com/Ion-Protocol/amplify-sdk/issues)
-- 💬 [GitHub Discussions](https://github.com/Ion-Protocol/amplify-sdk/discussions)
+[BSD-3-Clause](./LICENSE) © Paxos Labs