> ## 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.
# Smart Deposit Routing Events
> Webhook events emitted as stablecoins are routed through the Smart Deposit Address into a vault
Every smart deposit webhook includes the [common fields](/v1.0.0/intro/webhooks/event-catalog#common-fields), plus the routing and token context below. Each event also carries `received_amount` — the stablecoin amount detected at the Smart Deposit Address, in the input token's smallest unit.
## Shared Fields
| Field | Type | Description |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deposit_id` | `string` | Unique deposit identifier, prefixed with `pxl_dep_` (e.g. `"pxl_dep_8a3c9d2e-…"`). Treat it as an opaque string. Every event for the same deposit — `pending` through `confirmed`/`failed` and `finalized` — carries the same `deposit_id`. See [Tracking a deposit across events](#tracking-a-deposit-across-events). |
| `chain_id` | `string` | EIP 155 chain ID (e.g. `"11155111"`). |
| `chain_name` | `string` | Human-readable chain name (e.g. `"Ethereum Sepolia"`). |
| `organization_id` | `string` | Your organization UUID. |
| `customer_id` | `string \| null` | Optional customer identifier passed when creating the Smart Deposit Address. `null` if not provided. |
| `smart_deposit_address` | `string` | The Smart Deposit Address that received the stablecoins. |
| `user_destination_address` | `string` | End-user address where vault shares are minted. |
| `vault_address` | `string` | Target vault (Boring Vault) contract address. |
| `input_token_symbol` | `string` | Symbol of the deposited stablecoin (e.g. `"USDC"`). |
| `input_token_address` | `string` | Contract address of the deposited stablecoin. |
| `input_token_decimals` | `number` | Decimal places of the input token. |
| `received_amount` | `string` | Amount received at the Smart Deposit Address, in the input token's smallest unit. String for bigint serialization. Multiple transfers of the same token that arrive at the address in quick succession may be combined into **one** deposit with their total amount — don't assume a 1:1 mapping between on-ramp transactions and deposits. |
## Tracking a Deposit Across Events
Use `deposit_id` to tie a webhook to a deposit — it is minted when the deposit is first detected and repeated on every subsequent event for that deposit. Do not use the top-level `id` for this: `id` is unique per *event* (its job is [deduplicating redeliveries](/v1.0.0/intro/webhooks/common-implementation-patterns#idempotent-processing)), so the `pending` and `confirmed` events for one deposit have different `id` values but the same `deposit_id`.
A deposit emits one sequence: `pending`, then `confirmed` or `failed`, then — after `confirmed` only — `finalized`. Every sequence begins with `pending`: a `confirmed`, `failed`, or `finalized` event is only ever emitted for a `deposit_id` whose `pending` event was already emitted. As with any webhook system, *deliveries* can still reach your endpoint out of order — order by event semantics, not arrival time.
If a deposit fails with `remediation: "retained"`, the funds stay in the Smart Deposit Address and may be retried automatically. A retry is a new sequence with a **new** `deposit_id`, starting again from `pending`.
***
## `smart_deposit.deposit.pending`
Paxos Labs has received the stablecoins and initiated the process to deposit them into the vault.
```json theme={null}
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "smart_deposit.deposit.pending",
"timestamp": "2026-04-10T18:32:24.000Z",
"version": "v2",
"deposit_id": "pxl_dep_8a3c9d2e-6f41-4b0a-9c58-2d7e1f0a4b63",
"chain_name": "Ethereum Sepolia",
"chain_id": "11155111",
"organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
"customer_id": "user_abc123",
"smart_deposit_address": "0xsda0000000000000000000000000000000123",
"user_destination_address": "0xuda0000000000000000000000000000000000456",
"vault_address": "0xvlt0000000000000000000000000000000999",
"input_token_symbol": "USDC",
"input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"input_token_decimals": 6,
"received_amount": "10000000"
}
```
### Event-Specific Fields
None — `pending` carries only the shared fields above. It is emitted as soon as the stablecoin balance is detected, before any forward transaction exists, so there are no transaction hashes to report yet.
***
## `smart_deposit.deposit.confirmed`
Stablecoins have been successfully deposited into the vault and shares have been minted to the destination address.
```json theme={null}
{
"id": "0d9b7c15-3e82-47a6-b1f4-5c60d8e92a17",
"type": "smart_deposit.deposit.confirmed",
"timestamp": "2026-04-10T18:33:12.000Z",
"version": "v2",
"deposit_id": "pxl_dep_8a3c9d2e-6f41-4b0a-9c58-2d7e1f0a4b63",
"chain_name": "Ethereum Sepolia",
"chain_id": "11155111",
"organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
"customer_id": "user_abc123",
"smart_deposit_address": "0xsda0000000000000000000000000000000123",
"user_destination_address": "0xuda0000000000000000000000000000000000456",
"vault_address": "0xvlt0000000000000000000000000000000999",
"input_token_symbol": "USDC",
"input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"input_token_decimals": 6,
"received_amount": "10000000",
"forward_tx_hash": "0x1234",
"forward_tx_block_hash": "0x4567"
}
```
### Event-Specific Fields
| Field | Type | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `received_amount` | `string` | Amount received in the token's smallest unit. |
| `forward_tx_hash` | `string` | Transaction hash of the transaction that forwards funds from the Smart Deposit Address into the vault. |
| `forward_tx_block_hash` | `string` | Block hash of the forward transaction. |
***
## `smart_deposit.deposit.finalized`
Deposit finalized.
```json theme={null}
{
"id": "5e2f8a90-1b74-4c3d-a6e9-7f08b5d4c221",
"type": "smart_deposit.deposit.finalized",
"timestamp": "2026-04-10T18:36:45.000Z",
"version": "v2",
"deposit_id": "pxl_dep_8a3c9d2e-6f41-4b0a-9c58-2d7e1f0a4b63",
"chain_name": "Ethereum Sepolia",
"chain_id": "11155111",
"organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
"customer_id": "user_abc123",
"smart_deposit_address": "0xsda0000000000000000000000000000000123",
"user_destination_address": "0xuda0000000000000000000000000000000000456",
"vault_address": "0xvlt0000000000000000000000000000000999",
"input_token_symbol": "USDC",
"input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"input_token_decimals": 6,
"received_amount": "10000000",
"forward_tx_hash": "0x1234",
"forward_tx_block_hash": "0x4567"
}
```
### Event-Specific Fields
Same as `smart_deposit.deposit.confirmed`. Sent after the forward transaction reaches chain-specific finality.
***
## `smart_deposit.deposit.failed`
Unable to deposit for some reason. Customer notified with reason and remediation actions taken.
```json theme={null}
{
"id": "b41d6e83-9a20-4f5c-8d17-3e92a0c7f558",
"type": "smart_deposit.deposit.failed",
"timestamp": "2026-04-10T18:33:12.000Z",
"version": "v2",
"deposit_id": "pxl_dep_8a3c9d2e-6f41-4b0a-9c58-2d7e1f0a4b63",
"chain_name": "Ethereum Sepolia",
"chain_id": "11155111",
"organization_id": "700768ae-c71d-42cc-9ff9-13b777d6d379",
"customer_id": "user_abc123",
"smart_deposit_address": "0xsda0000000000000000000000000000000123",
"user_destination_address": "0xuda0000000000000000000000000000000000456",
"vault_address": "0xvlt0000000000000000000000000000000999",
"input_token_symbol": "USDC",
"input_token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"input_token_decimals": 6,
"received_amount": "10000000",
"forward_tx_hash": "0x1234",
"forward_tx_block_hash": "0x4567",
"error": "Vault cap reached",
"remediation": "refunded"
}
```
### Event-Specific Fields
| Field | Type | Description |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `received_amount` | `string` | Amount received in the token's smallest unit. |
| `forward_tx_hash` | `string \| null` | Transaction hash of the forward attempt. `null` if the transaction was never sent. |
| `forward_tx_block_hash` | `string \| null` | Block hash of the forward attempt. `null` if the transaction was never sent. |
| `error` | `string` | Human-readable error describing why the deposit failed (e.g., vault cap reached, predicate failure, out of gas). |
| `remediation` | `string` | Where the funds ended up. One of `refunded`, `recovered`, `retained` — see below. |
### Remediation Values
Branch on `remediation` rather than parsing `error`, which is free-form prose intended for humans and may change at any time.
| Value | Meaning | Action for you |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `refunded` | The deposit could not proceed (vault cap reached, vault paused, slippage, etc.), so the stablecoins were sent back to the end-user's destination address on-chain. | Tell your end-user their funds were returned. `forward_tx_hash` is the on-chain proof. |
| `recovered` | The end-user cannot legally hold the input or share token (sanctions screening failure, blacklisted or frozen address), so the stablecoins were swept to a Paxos Labs recovery wallet. | Do not tell the user their funds were returned — they were not. Escalate through your compliance process. |
| `retained` | No on-chain remediation ran. The stablecoins are still sitting in the Smart Deposit Address. | No action required. We are alerted automatically and will investigate; the deposit may be retried automatically. Show this to your end-user as *delayed*, not failed — a successful retry arrives as a new `pending` → `confirmed` sequence with a **new** `deposit_id`. |
`remediation` is only present on `smart_deposit.deposit.failed`. It is never sent on `pending`, `confirmed`, or `finalized` events, where there is nothing to remediate.
`remediation: "refunded"` and `remediation: "recovered"` always carry a non-null `forward_tx_hash`, because the remediation itself is an on-chain action. `remediation: "retained"` always carries `forward_tx_hash: null`.