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, 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.
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), 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.