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

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 `error` and `forward_tx_hash` fields to provide an appropriate notification to your end-user.

If `forward_tx_hash` is set, Paxos Labs has already executed on-chain remediation (refund to the user or recovery to one of our internal wallets if a user was found to be sanctioned). If it's not set, we encountered an unexpected error and funds remain in the Smart Deposit Address. Rest assured, we have been alerted and are investigating any issues of this category.

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.