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

# Developers

> Integrate Smart Deposit Routing into your application.

# Developers

Integrate Smart Deposit Routing into your application to automatically allocate deposits across supported destinations.

***

## Technical Integration Outline

A typical Smart Deposit Routing setup includes:

### 1. Initialize SDK and Configure API Keys

Install the Paxos Labs SDK or REST API client and configure credentials for your program.

Define the accounts, input tokens, and chains you intend to support.

### 2. Register a Webhook URL

Register an HTTPS webhook URL in the [Paxos Labs Console](https://console.paxoslabs.com) and subscribe to the smart deposit event types ([event reference](/v1.0.0/intro/webhooks/event-catalog/smart-deposit-routing)).

Follow the [webhook quick start](/v1.0.0/intro/webhooks/quickstart) to store your signing secret (starts with `pxlwh_`), subscribe to every event starting with `smart_deposit`, and verify a test delivery.

You'll use these events to keep your UI in sync without watching the chain yourself.

### 3. Generate a Deposit Address

Call the Smart Deposit Routing API to generate a deterministic address for a given end-user, account, input token, and chain.

The same inputs always produce the same address, so addresses can be safely re-derived on demand.

#### Optional Customer Identifier

Pass the optional `customerId` parameter to **generate unique deposit addresses** per customer:

```json theme={null}
POST /v2/amplify/smartDepositAddresses
{
  "userDestinationAddress": "0xDestinationAddress",
  "vaultAddress": "0xVaultAddress",
  "inputToken": "0xUSDCAddress",
  "chainId": 1,
  "customerId": "user_abc123"
}
```

When `customerId` is provided:

* Each unique `customerId` produces a distinct deposit address, even when other parameters are identical
* The `customerId` is included in webhook payloads for reconciliation
* Must contain only alphanumeric characters, hyphens, and underscores (max 256 characters)

When `customerId` is omitted, the address is derived from `(userDestinationAddress, vaultAddress, inputToken, chainId)` alone.

### 4. Hand the Address to Your On-Ramp Provider

Pass the generated address to your on-ramp provider as the destination for your end-user's fiat purchase.

The end-user completes their fiat payment inside your app exactly as they would for any on-ramp — no additional signatures or steps required.

### 5. React to Webhook Events

Every event for a deposit carries the same `deposit_id`, so you can track it across its lifecycle. A deposit follows one of two paths: `pending` → `confirmed` → `finalized`, or `pending` → `failed` (failed deposits never emit `finalized`). If a failure leaves funds `retained` in the Smart Deposit Address, any automatic retry starts a new lifecycle with a new `deposit_id`. See [tracking a deposit across events](/v1.0.0/intro/webhooks/event-catalog/smart-deposit-routing#tracking-a-deposit-across-events).

The first time you see a `deposit_id` is the `pending` event — deposits are detected on-chain, so the ID is never returned by an API call. On `pending`, resolve your end-user from `customer_id` (or `smart_deposit_address`), create your internal deposit record keyed by `deposit_id`, and let every later event update that record.

When you receive the `smart_deposit.deposit.confirmed` webhook, notify your end-user that their on-ramped funds are now earning yield!

Or, if you receive a `smart_deposit.deposit.failed` event, read the `remediation` field to decide what to tell your end-user, and the `error` field for the underlying reason:

* `refunded` — the deposit couldn't proceed, so we sent the stablecoins back to the end-user's destination address. Tell them their funds were returned; `forward_tx_hash` is the on-chain proof.
* `recovered` — the end-user cannot legally hold the token (sanctions screening failure, blacklisted or frozen address), so we swept the stablecoins to a Paxos Labs recovery wallet. Their funds were **not** returned — escalate through your compliance process.
* `retained` — we encountered an unexpected error and the funds remain in the Smart Deposit Address. Rest assured, we have been alerted and are investigating any issues of this category. Present this to your end-user as *delayed*, not failed — a successful retry arrives as a fresh `pending` → `confirmed` sequence under a **new** `deposit_id`.

Branch on `remediation`, not on `error` or `forward_tx_hash` — `error` is free-form prose meant for humans and may change at any time.

See the [Smart Deposit Routing Events](/v1.0.0/intro/webhooks/event-catalog/smart-deposit-routing) reference for payloads, and the [event catalog](/v1.0.0/intro/webhooks/event-catalog#common-patterns) for handler examples.