Settlements

A settlement is the canonical record of one UDA deposit moving from its source chain to the destination chain and token. One deposit produces one settlement, and every settlement is fetchable forever via GET /v1/settlements/{id} (see the API reference).

Lifecycle

Settlements go through a small state machine:

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.

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} and from uda.settlement.* webhooks.

Scenarios

Every settlement is tagged with one of four scenario values. The Routing Engine uses the scenario to pick providers and pricing.

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

GET /v1/settlements/{id}

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

Listing settlements

For reconciliation or a user-facing deposit history, list settlements by UDA:

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.

List settlements by reference

When you know the on-chain deposit transaction that funded a settlement but not its internal settlement id, look it up by reference:

GET /v1/uda/settlements/by-reference?reference={deposit_tx_hash}

The reference query parameter is required. It is currently the on-chain deposit transaction id — the transaction your user broadcast to the UDA address. This is the lookup to reach for when the caller knows what they paid with but not the internal id Stridge assigned.

A single deposit transaction can carry more than one deposit, so the response is always a list — data is empty when nothing matches.

curl 'https://api.stridge.dev/v1/uda/settlements/by-reference?reference=0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c' \
  -H 'X-API-Key: '"$STRIDGE_API_KEY"''

Response (200) — count plus a data array of settlement records:

{
  "reference": "0xb7b493e68121ce6c7c39b6e0dce56fd45899277a8a85e5c524a718a00837355c",
  "count": 1,
  "data": [
    {
      "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": {
        "network_id": 9006,
        "network_name": "bsc",
        "address": "0x3b7e9d1a5c2f4b8e6d0c9f3a2b1e4d5c7a9b8e0f",
        "asset_address": "",
        "asset_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",
        "platform": "0",
        "provider": "18485000000000",
        "total": "18485000000000"
      },
      "settlement": {
        "network_id": 9001,
        "network_name": "arbitrum",
        "address": "0x8f4a2c9e1b3d7f5a6c8e0d9b2a4c6e8f0a2c4d6e",
        "asset_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
        "asset_symbol": "USDC",
        "amount": "3140",
        "tx_hash": "0x158ffc8b098ae63d697485a75666a337eaab18a2167ff417861f3209dffce29b",
        "settled_at": "2026-04-24T06:56:17Z"
      },
      "error": ""
    }
  ]
}

A 400 is returned when reference is missing; a 500 signals an internal error — retry with backoff.

Quoting before a deposit

Use GET /v1/uda/quote (see the API reference) 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.

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 asset sent — any asset outside accepted_assets 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 — payload-by-payload reference.
• Routing rules — how a settlement's destination is chosen.
• API reference — GET /v1/settlements/{id}, GET /v1/uda/{id}/settlements, and GET /v1/uda/settlements/by-reference.