# Settlements \[How a deposit becomes funds on the destination chain] A **settlement** is the canonical record of one UDA deposit moving from its source chain to the destination chain and token. One deposit produces exactly one settlement, and every settlement is fetchable forever via [`GET /v1/settlements/{id}`](/api-reference/settlements/get-a-settlement). ## Lifecycle ``` deposit.confirmed ─▶ uda.settlement.created ─▶ uda.settlement.completed │ ▲ └───────── (on failure) ────▶ uda.settlement.failed ``` Settlements go through a small state machine: | `status` | Meaning | | ----------- | --------------------------------------------------------------------------------- | | `created` | Deposit confirmed; Routing Engine has picked a route and begun execution. | | `completed` | Destination tx landed; funds are in the destination token. | | `failed` | All provider attempts exhausted — surfaced with an `error` string. | Intermediate states (quoting, signing, broadcasting) are not exposed externally. From the integrator's point of view a settlement is `created`, then either `completed` or `failed`. :::info Retire a UDA at any time with [`DELETE /v1/uda/{id}`](/api-reference/uda/retire-a-uda-address). In-flight settlements keep running to completion; only **new** deposits stop triggering settlements. ::: ## Dashboard: settlement detail In the Stridge **Dashboard**, each settlement has a **detail** view: **status** (for example completed), **UDA** id, **scenario** (such as same-chain swap), **provider** (for example LI.FI), and a **flow** from the **source deposit** (amount, asset, address, source tx, confirmed time) to the **destination** (settled amount, address, settled time), plus **fees**. It matches the data you will reconcile from [`GET /v1/settlements/{id}`](/api-reference/settlements/get-a-settlement) and from [`uda.settlement.*`](/webhooks) webhooks.  ## Scenarios Every settlement is tagged with one of four `scenario` values. The Routing Engine uses the scenario to pick providers and pricing. | `scenario` | Source | Destination | Route | | -------------------------- | --------------------------- | --------------------------- | ------------------------- | | `same_chain_same_token` | USDC on Arbitrum | USDC on Arbitrum | Direct transfer | | `same_chain_diff_token` | USDT on Arbitrum | USDC on Arbitrum | DEX swap | | `cross_chain_same_token` | USDC on Base | USDC on Arbitrum | Bridge | | `cross_chain_diff_token` | BNB on BSC | USDC on Arbitrum | Swap + bridge | Under the hood, same-chain same-token settles without a third-party provider; the other three scenarios quote across LI.FI and Relay and pick the best executable quote. ## The settlement record ```bash GET /v1/settlements/{id} ``` ```json { "id": "bcc2b0c1-f75c-43b2-b1bc-c44437d775f4", "status": "completed", "uda_id": "31d32b68-e455-42b7-9d39-d2904adbe1b8", "created_at": "2026-04-24T06:56:06Z", "updated_at": "2026-04-24T06:56:17Z", "deposit": { "chain_id": 56, "network_name": "bsc", "address": "0x3b7e9d1a5c2f4b8e6d0c9f3a2b1e4d5c7a9b8e0f", "token_address": "", "token_symbol": "BNB", "amount": "5000000000000000", "tx_hash": "0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c", "confirmed_at": "2026-04-24T06:55:59Z" }, "route": { "provider": "lifi", "type": "cross_chain_diff_token", "time_ms": 11000 }, "fees": { "fee_amount": "18485000000000" }, "settlement": { "chain_id": 42161, "network_name": "arbitrum", "address": "0x8f4a2c9e1b3d7f5a6c8e0d9b2a4c6e8f0a2c4d6e", "token_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "token_symbol": "USDC", "amount": "3140", "tx_hash": "0x158ffc8b098ae63d697485a75666a337eaab18a2167ff417861f3209dffce29b", "settled_at": "2026-04-24T06:56:17Z" } } ``` | Field | Purpose | | ----------------- | ------------------------------------------------------------------------------- | | `deposit.*` | Everything about the source-chain transaction (chain, token, amount, tx hash) | | `settlement.*` | Everything about the destination-chain delivery | | `route.provider` | Which provider executed the route (`lifi`, `relay`, `stridge` for same-chain) | | `route.type` | Settlement scenario | | `route.time_ms` | Wall-clock latency from `created` to `completed` | | `fees.fee_amount` | Total fee in the destination token's smallest unit | | `error` | Present only when `status == "failed"`; human-readable failure reason | ## Listing settlements For reconciliation or a user-facing deposit history, list settlements by UDA: ```bash GET /v1/uda/{uda_id}/settlements?limit=50&offset=0 ``` Results are paginated. Every entry has the same shape as `GET /v1/settlements/{id}`, so you can hydrate a deposit ledger with one round trip per page. ## Quoting before a deposit Use [`GET /v1/uda/quote`](/api-reference/uda/get-a-cross-chain-cross-token-quote) to show users an expected fee and settlement time **before** they broadcast. The response mirrors the shape of a completed settlement and carries an `expires_at` — always re-quote if the user hesitates long enough for the quote to expire. ```bash GET /v1/uda/quote? from_chain_id=56 &from_token=0x0000000000000000000000000000000000000000 &to_chain_id=42161 &to_token=0xaf88d065e77c8cc2239327c5edb3a432268e5831 &amount=5000000000000000 &from_address=0x3b7e9d1a5c2f4b8e6d0c9f3a2b1e4d5c7a9b8e0f ``` ## Failure modes * **`uda.settlement.failed`** — all provider attempts exhausted. The deposit remains untouched; manual resolution via the dashboard is possible. No automatic retry. * **Provider timeout** — Stridge re-quotes and re-executes transparently. You will only see `created → completed`. * **Dust deposits** — deposits below the routable minimum for a scenario complete normally but deliver a very small `destination_amount`. Consider enforcing a minimum in your UI. * **Wrong token sent** — any token outside `accepted_tokens` is ignored and does not produce a settlement. Funds stay at the UDA address; the account owner can manually move them via the dashboard. ## Reconciliation tips * Persist `(deposit.tx_hash, settlement.tx_hash, status)` on every `uda.settlement.*` webhook; replay from `GET /v1/uda/{id}/settlements` if your queue ever falls behind. * Join `deposit.confirmed` and `uda.settlement.*` on the deposit id (`deposit.confirmed.id == settlement.deposit.tx_hash`'s settlement id — same UUID). * For accounting, `fees.fee_amount` is always in the destination token's smallest unit. ## Next * [UDA Webhook events](/uda/webhooks) — payload-by-payload reference. * [API reference — `GET /v1/settlements/{id}`](/api-reference/settlements/get-a-settlement) * [API reference — `GET /v1/uda/{id}/settlements`](/api-reference/uda/list-settlements-for-a-uda-address)