<!--
Sitemap:
- [Stridge — The infrastructure bridging crypto payments](/index): Crypto payment infrastructure for modern fintechs. Accept on any chain, settle through the cheapest route, and pay out in any asset — all from a single SDK.
- [API Reference](/api-reference/): Stridge REST API reference — complete endpoint documentation for deposits, payouts, Universal Deposit Addresses, settlements, and supported networks.
- [Changelog](/changelog): Release notes for Stridge SDKs and developer tools.
- [Stridge Gateway Kit](/gateway/): Drop-in deposit and withdraw flows for crypto apps. Mount a single React provider, render a dialog, and ship any-to-any payments in minutes.
- [Getting Started](/getting-started): Get started with Stridge — pick your integration shape, generate keys, and make your first call from the React Kit, the TypeScript SDK, or the REST API.
- [Supported Networks](/networks): Blockchain networks and tokens supported by the Stridge payment infrastructure — network_id (SLIP-44), EIP-155 chain IDs, and the available native and stablecoin assets per chain.
- [TypeScript SDK](/sdk/): TypeScript client for the Stridge Gateway API. Used internally by @stridge/kit and exposed for backend and server integrations that need direct API access.
- [Security](/security/): Stridge Security — how the Stridge KMS protects wallet keys and signs transactions without ever exposing private keys.
- [Universal Deposit Addresses](/uda/): Universal Deposit Addresses (UDA) — one multi-chain deposit address per user, with automatic cross-chain settlement to a fixed destination.
- [Webhooks](/webhooks/): Stridge webhooks — signed HTTP POSTs for deposits, UDA settlements, wallets, and balances. Verify HMAC, handle retries, and use the Dashboard to inspect event payloads.
- [Gateway HTTP API](/gateway/http): Raw HTTP contract for the Stridge Gateway — supported-assets catalogue, gateway/start provisioning, and per-owner status polling.
- [UDA Quickstart](/uda/quickstart): Create your first Universal Deposit Address and trace a deposit end-to-end — from the POST call, through webhooks, to a settled transaction on the destination chain.
- [Settlements](/uda/settlements): UDA settlements — lifecycle, routing scenarios, fees, and the settlement record API. Reconcile deposits with webhooks; the Dashboard shows each settlement end-to-end.
- [UDA Webhook Events](/uda/webhooks): Reference for the three webhook events UDA deposits emit — deposit.confirmed, uda.settlement.created, and uda.settlement.completed — with payloads and lifecycle guidance.
- [Get a single deposit transaction by ID](/api-reference/deposits/get-a-single-deposit-transaction-by-id): Get details of a specific deposit transaction by its unique ID
- [Get a single deposit transaction by transaction id](/api-reference/deposits/get-a-single-deposit-transaction-by-transaction-id): One row per matching tx_id; multiple same-tx transfers are separate rows. Returns the latest by on-chain time (then id). Use GET /v1/deposits with tx_id filter
- [List deposit transactions](/api-reference/deposits/list-deposit-transactions): Get a paginated list of deposit transactions for the authenticated tenant with filtering support
- [Get blockchain assets](/api-reference/networks/get-blockchain-assets): Get a list of all supported blockchain assets (tokens and native assets).
- [Get blockchain networks](/api-reference/networks/get-blockchain-networks): Get a list of all supported blockchain networks.
- [Get network list](/api-reference/networks/get-network-list): Get a public list of all networks with category grouping.
- [Get tenant network](/api-reference/networks/get-tenant-network): Get a specific network for the authenticated tenant by network ID and contract address
- [Get tenant networks](/api-reference/networks/get-tenant-networks): Get a list of networks available to the authenticated tenant with their enabled status
- [Update tenant network status](/api-reference/networks/update-tenant-network-status): Update the enabled status of a network for the authenticated tenant
- [Create payout](/api-reference/payouts/create-payout): Creates a new payout from the tenant's vault wallet to an external address
- [Create payout with USD amount](/api-reference/payouts/create-payout-with-usd-amount): Creates a new payout converting a USD amount to crypto at current rate
- [Get payout by ID](/api-reference/payouts/get-payout-by-id): Retrieves a payout by its ID
- [Get vault address by network](/api-reference/payouts/get-vault-address-by-network): Get the vault address for a specific network
- [Get vault balances](/api-reference/payouts/get-vault-balances): Get balances for all vault addresses with optional filtering
- [Get vault total value](/api-reference/payouts/get-vault-total-value): Get the total USD value across all vault assets
- [List payouts](/api-reference/payouts/list-payouts): Lists payouts for a vault with filtering and pagination
- [List vault addresses](/api-reference/payouts/list-vault-addresses): Get all vault addresses for the authenticated tenant
- [List vaults](/api-reference/payouts/list-vaults): List all vault accounts for the authenticated tenant
- [Transfer from vault to external address](/api-reference/payouts/transfer-from-vault-to-external-address): Transfer assets from the tenant's vault wallet to an external address.
- [Get a settlement](/api-reference/settlements/get-a-settlement): Fetch a single settlement by ID. A settlement is created per confirmed deposit on a UDA address and carries the lifecycle state, scenario, and routing tx ids.
- [Create a UDA address](/api-reference/uda/create-a-uda-address): Allocate a new Universal Deposit Address for the tenant. If a UDA for the (tenant, owner) pair already exists, the existing record is returned with 200 instead
- [Get a cross-chain / cross-token quote](/api-reference/uda/get-a-cross-chain-cross-token-quote): Returns an indicative quote for routing from/to given (chain, token) pair. USD fields are omitted until a price feed is wired in.
- [Get a UDA address](/api-reference/uda/get-a-uda-address): Fetch a single UDA address by ID, including its delegation status.
- [List settlements for a UDA address](/api-reference/uda/list-settlements-for-a-uda-address): List all settlements that have been created for a given UDA address, optionally paginated.
- [List UDA addresses](/api-reference/uda/list-uda-addresses): List UDA addresses belonging to the authenticated tenant. Supports filtering by owner and status and pagination via limit/offset.
- [List UDA-supported chains](/api-reference/uda/list-uda-supported-chains): Returns every chain with `uda_support=true` along with its native currency and configured token contracts. Rows are grouped by network.
- [Retire a UDA address](/api-reference/uda/retire-a-uda-address): Mark a UDA address as retired. Future deposits will no longer trigger settlements; any already-confirmed settlements continue to run to completion.
- [Update a UDA address](/api-reference/uda/update-a-uda-address): Update the destination, accepted tokens, or status of an existing UDA. Owner is immutable.
-->

# UDA Webhook Events \[Three events cover the full UDA deposit lifecycle]

Every UDA deposit produces exactly three webhook deliveries:

| Order | Event                        | What it means                                                       |
| ----- | ---------------------------- | ------------------------------------------------------------------- |
| 1     | `deposit.confirmed`          | Source-chain deposit confirmed at the UDA address                   |
| 2     | `uda.settlement.created`     | Routing Engine accepted the deposit and is executing the route      |
| 3     | `uda.settlement.completed`   | Destination transaction landed in the destination token             |

All three share the
[standard Stridge webhook envelope](/webhooks) — `id`, `type`,
`time`, `version`, signed with HMAC SHA-256. The payloads below are
the inner `payload` object.

:::info
If a settlement fails permanently, the third event is
`uda.settlement.failed` instead of `.completed` and includes an
`error` field. Everything else is identical.
:::

## Subscribing

Register an endpoint in the
[dashboard](https://beta.dashboard.stridge.com) and opt into the
three event types. Stridge supports multiple subscribers — one
endpoint per environment is the recommended pattern.

Always verify the `webhook-signature` before trusting the body. See
[Signature verification](/webhooks#signature-verification) for
example code in Node.js, Go, and Python.

## `deposit.confirmed`

Fires once the source-chain deposit transaction has reached the
required number of confirmations. `to_wallet_category: "uda"` flags
the deposit as routed through a UDA — regular wallet deposits carry
the same event type but a different category.

```json
{
  "id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4",
  "time": "2026-04-24T06:55:59Z",
  "asset": "BNB",
  "symbol": "BNB",
  "owner": "31d32b68-e455-42b7-9d39-d2904adbe1b8",
  "tx_id": "0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c",
  "balance": {
    "raw": "5000000000000000",
    "usd": "3.17565",
    "amount": "0.005"
  },
  "decimal": 18,
  "network_id": "9006",
  "network_symbol": "bsc",
  "block_number": "94359674",
  "from_address": "0x5a9b7c3e2f8d4a1b6c0e9f7a3b8c2d5e1f4a7b9c",
  "to_address": "0x3b7e9d1a5c2f4b8e6d0c9f3a2b1e4d5c7a9b8e0f",
  "contract_address": "",
  "is_token_transfer": false,
  "scanner_url": "/tx/0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c",
  "to_wallet_category": "uda",
  "from_wallet_category": "external"
}
```

| Field                  | Type      | Notes                                                                             |
| ---------------------- | --------- | --------------------------------------------------------------------------------- |
| `id`                   | string    | Deposit id — same as `deposit_id` on the settlement events                        |
| `owner`                | string    | **UDA id** for UDA deposits (not the tenant-level `owner` you sent on create)     |
| `asset` / `symbol`     | string    | The deposited asset symbol                                                        |
| `tx_id`                | string    | Source-chain transaction hash                                                     |
| `balance.raw`          | string    | Amount in the asset's smallest unit (stringified integer)                         |
| `balance.amount`       | string    | Human-readable amount (already divided by `decimal`)                              |
| `balance.usd`          | string    | Indicative USD value at detection                                                 |
| `network_id`           | string    | Stridge internal network id                                                       |
| `network_symbol`       | string    | Network slug (`ethereum`, `bsc`, `base`, `arbitrum`, …)                           |
| `is_token_transfer`    | boolean   | `true` for ERC-20 transfers, `false` for native coin                              |
| `contract_address`     | string    | ERC-20 token contract (empty when `is_token_transfer` is `false`)                 |
| `to_address`           | string    | UDA deposit address that received the funds                                       |
| `to_wallet_category`   | enum      | `"uda"` for UDA deposits — use this to filter out regular wallet deposits         |
| `from_wallet_category` | enum      | `"external"` for third-party senders                                              |
| `scanner_url`          | string    | Relative path on the chain's block explorer                                       |

:::tip
The `owner` field on `deposit.confirmed` is the **UDA id**, not the
owner string you passed to `POST /v1/uda`. Use it to look up the UDA
record or to join with `uda.settlement.*` events via `uda_address_id`.
:::

## `uda.settlement.created`

Fires immediately after the Routing Engine accepts the deposit and
opens a settlement. At this point the route has been picked but not
yet executed, so `destination_amount` and `fee_amount` are zero.

```json
{
  "id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4",
  "state": "created",
  "scenario": "cross_chain_diff_token",
  "deposit_id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4",
  "deposit_tx_id": "0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c",
  "uda_address_id": "31d32b68-e455-42b7-9d39-d2904adbe1b8",
  "source_network_id": "9006",
  "source_token_address": "",
  "source_amount": "5000000000000000",
  "destination_network_id": "9001",
  "destination_token_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "destination_address": "0x8f4a2c9e1b3d7f5a6c8e0d9b2a4c6e8f0a2c4d6e",
  "destination_amount": "0",
  "fee_amount": "0",
  "created_at": "2026-04-24T06:56:06Z",
  "updated_at": "2026-04-24T06:56:06Z"
}
```

| Field                     | Type    | Notes                                                                       |
| ------------------------- | ------- | --------------------------------------------------------------------------- |
| `id` / `deposit_id`       | string  | Settlement id and originating deposit id (equal on first event)             |
| `state`                   | enum    | `created`                                                                    |
| `scenario`                | enum    | `same_chain_same_token`, `same_chain_diff_token`, `cross_chain_same_token`, `cross_chain_diff_token` |
| `uda_address_id`          | string  | UDA record the deposit landed on                                            |
| `source_*`                |         | Network, token, amount on the source side                                   |
| `destination_*`           |         | Where the funds will be delivered (amount is `0` until `completed`)         |
| `fee_amount`              | string  | Routing fee in destination-token smallest units (populated on `completed`)  |
| `source_token_address`    | string  | Empty string for native coins                                               |

## `uda.settlement.completed`

Fires once the destination transaction is on-chain. `state` is
`completed`, `destination_amount` and `fee_amount` are populated, and
`source_routing_tx_id` gives you the outbound tx on the destination
chain.

```json
{
  "id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4",
  "state": "completed",
  "provider": "lifi",
  "scenario": "cross_chain_diff_token",
  "deposit_id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4",
  "deposit_tx_id": "0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c",
  "uda_address_id": "31d32b68-e455-42b7-9d39-d2904adbe1b8",
  "source_network_id": "9006",
  "source_token_address": "",
  "source_amount": "5000000000000000",
  "source_routing_tx_id": "0x158ffc8b098ae63d697485a75666a337eaab18a2167ff417861f3209dffce29b",
  "destination_network_id": "9001",
  "destination_token_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "destination_address": "0x8f4a2c9e1b3d7f5a6c8e0d9b2a4c6e8f0a2c4d6e",
  "destination_amount": "3140",
  "fee_amount": "18485000000000",
  "created_at": "2026-04-24T06:56:06Z",
  "updated_at": "2026-04-24T06:56:17Z"
}
```

| Field                     | Type    | Notes                                                                       |
| ------------------------- | ------- | --------------------------------------------------------------------------- |
| `state`                   | enum    | `completed` on success; `failed` with an `error` field on terminal failure  |
| `provider`                | string  | Bridge/swap provider used (`lifi`, `relay`, …)                              |
| `destination_amount`      | string  | Delivered amount in the destination token's smallest unit                   |
| `fee_amount`              | string  | Total fee (gas + protocol) in the destination token's smallest unit         |
| `source_routing_tx_id`    | string  | Destination-chain transaction that delivered the funds                      |

## Full example timeline

```
t = 0.0s   User sends 0.005 BNB on BSC → UDA address
t = 7.0s   Observer detects tx                          → deposit.confirmed
t = 7.2s   UDA opens settlement, picks route via LI.FI  → uda.settlement.created
t = 18.0s  LI.FI swap + bridge completes on Arbitrum    → uda.settlement.completed
```

Total wall time for a cross-chain, cross-token settlement is
typically 10–30 seconds on L2 destinations, and 60–90 seconds on
Ethereum mainnet.

## Consumer checklist

* **Verify every signature.** See
  [Signature verification](/webhooks#signature-verification).
* **Deduplicate by envelope `id`.** Stridge retries failed deliveries
  up to six times; every retry reuses the same `id`.
* **Treat `state` as the source of truth, not event ordering.** If
  `created` is delayed and `completed` lands first, trust `state` +
  `updated_at` rather than arrival order.
* **Join `deposit.confirmed` and settlement events via the deposit
  id.** `deposit.confirmed.id == uda.settlement.*.deposit_id`.
* **Mirror `uda.settlement.failed`.** Treat it as terminal and
  surface the `error` field to support tooling; Stridge does not
  retry failed settlements automatically.

## Next

* [Settlements](/uda/settlements) — state machine, failure modes,
  and the `GET /v1/settlements/{id}` contract.
* [General webhooks guide](/webhooks) — envelope, retries, signing
  algorithm.