# Escrows

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/escrows
Find every escrow of your system in the Console, read who holds what in it, check open locks and their reclaim dates, and trace each deposit, lock and payment.

**Escrows**, under "Asset lifecycle" in the Console sidebar, lists every escrow of your system and shows which owner holds how much unlocked or locked in each, which locks are still open, and what happened to a lock. The screen is read-only: the features that use escrows create them, and moving units out is a Platform API task. An escrow is an on-chain contract that holds tokens for their owners while something is pending. The platform puts every escrow on the system's compliance bypass list when it creates it, so the token's compliance rules do not refuse a deposit into it. Three features use one:

- A [trading venue](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) holds the units each open order commits.
- A [custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals) holds deposited tokens that wait for screening, its own funding that pays withdrawals, and the custody receipts a client returns to withdraw.
- A [bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail#pay-out-from-an-escrow) wallet holds the tokens of each cash-out until the bank pays or the cash-out is released.

[Escrow](https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow) explains the rules every escrow enforces.

![Escrows list with the Escrow, Add-on, Controller, Tokens, Held, Open locks and Created columns](https://docs.settlemint.com/docs/screenshots/console-escrows-list.light.en.webp)

[Screenshot] The "Escrows" table shows one row per escrow.

Each row shows the escrow's label and address, the "Add-on" that controls it, the "Controller" address, the number of "Tokens", what it "Held" per token, its "Open locks" and its "Created" date.

## Before you start [#before-you-start]

- The Owner or Platform admin role: the sidebar shows **Escrows** to an organisation Owner or a Platform admin, and to no other role. Any other caller that reads an escrow through the Platform API gets a not-found response.
- An escrow add-on on the system: **Escrows** appears in the sidebar once the system has an escrow add-on deployed.
- An escrow to read: an escrow appears once a trading venue or a custody gateway is created, or a bank rail manager who holds the Escrow manager role creates the rail wallet's escrow.

## Steps [#steps]

### Open the escrows list [#open-the-escrows-list]

Open "Asset lifecycle", then **Escrows**. The title shows how many escrows your system has, and the line under it reads "Where add-ons hold tokens on behalf of their owners, and how much of each token is locked."

| Column | What it shows |
| --- | --- |
| **Escrow** | The label the escrow was given when it was created, such as the venue's name, with the escrow's address under it. |
| **Add-on** | **Trading venue**, or **Other** for every other controller, such as a custody gateway or a bank rail wallet. Match the **Controller** address to tell them apart. |
| **Controller** | The address that moves the escrow's balances. For a trading venue it links to the venue. |
| **Tokens** | How many tokens the escrow owes a non-zero amount of. |
| **Held** | Unlocked plus locked units per token, for the first three tokens, then **+N more**. Open the escrow to see every token on **Balances**. An escrow that owes nothing shows a dash. |
| **Open locks** | How many locks still hold units. |
| **Created** | The date the escrow was created. |

The table loads 50 rows a page from the server. Sort by "Escrow", "Controller", "Tokens", "Open locks" or "Created". To narrow the list to one kind of controller, use the **Add-on** filter in the table toolbar, which shows the count for each kind. The table has no search box.

When the system has no escrows, the page reads "No escrows yet" with an **Open venues** button instead of a table. Creating a venue creates its escrow.

### Open one escrow [#open-one-escrow]

Select a row. The escrow opens with its label as the title. Under the title the header names the add-on kind and reads "Controlled by" with the controller's address, which links to the venue for a trading venue. Two figures follow: "Distinct tokens held", with the amounts per token under it, and "Open locks". Select **Show locks** under "Open locks" to go to the "Locks" tab.

Three tabs sit below the header: "Balances", "Locks" and "Events".

## Read who holds what [#read-who-holds-what]

The **Balances** tab opens first.

![One escrow's header with its figures, and the Balances tab with Owner, Token, Free, Locked and Total columns](https://docs.settlemint.com/docs/screenshots/console-escrow-detail-balances.light.en.webp)

[Screenshot] The escrow page shows the header figures above the Balances tab, which has one row per owner and token.

The header shows the escrow's label as the title, the add-on kind, "Controlled by" with the controller's address, and the "Distinct tokens held" and "Open locks" figures, above the "Balances", "Locks" and "Events" tabs. The table shows "Owner", "Token", "Free", "Locked" and "Total" for each row.

Each row is one owner's position in one token. **Free** is the owner's unlocked balance in this escrow, which the owner may withdraw and a token custodian may move with a forced transfer. "Locked" is what sits in the owner's open locks, and "Total" adds the two. When the owner is the escrow's own controller, the owner cell adds the add-on kind and "(controller)". A custody gateway's own funding, for example, reads "Other (controller)".

The rows open ordered by owner, then token. Sort by "Owner", "Token", "Free" or "Locked". Sorting by amount compares whole tokens, not base units. A token without a symbol sorts last.

A token the platform has not indexed shows its short address. Its amount shows in base units, such as **2500 units**, because the Console cannot scale an amount without the token's decimals.

Below the table, open the collapsed **Technical** section for the "Escrow address" and the escrow's on-chain "Identity".

## Check open locks [#check-open-locks]

Select the **Locks** tab. The "Status" filter starts on "Open", so the table shows the locks that still hold units.

![The Locks tab with the Status filter on Open and the Owner, Token, Remaining, Reclaimable from, Status and Lock columns](https://docs.settlemint.com/docs/screenshots/console-escrow-detail-locks.light.en.webp)

[Screenshot] The Locks tab shows a table of the escrow's open locks with "Owner", "Token", "Remaining", "Reclaimable from", "Status" and "Lock" columns, and the "Status" filter set to "Open" in the toolbar.

"Remaining" is what the lock still holds. "Reclaimable from" is the moment after which any wallet may send a reclaim that returns the units to the owner's unlocked balance. A lock past that moment carries a **Reclaimable now** badge. A lock its owner can never reclaim reads "No owner exit". It holds units the owner already agreed to hand over, such as the legs of a matched trade waiting for delivery, and it empties when the controller pays, unlocks or relocks it, or a custodian moves it with a forced transfer.

The locks open newest first. Sort by "Lock", "Owner", "Token", "Remaining" or "Reclaimable from". In ascending order by "Reclaimable from", a lock with no owner exit sorts after every dated lock.

Change the **Status** filter to see locks that are empty. The status names the last move on the lock:

| Status | What emptied the lock |
| --- | --- |
| **Open** | Nothing. The lock still holds units. |
| **Unlocked** | The controller returned the units to the owner's unlocked balance. |
| **Relocked** | The controller moved the units into a new lock. |
| **Paid** | The controller paid the units out. |
| **Booked** | The controller moved the units to another owner's unlocked balance. |
| **Reclaimed** | A wallet reclaimed the lock after its **Reclaimable from** moment. |
| **Forced** | A token custodian's forced transfer emptied the lock. |

## Trace events [#trace-events]

Select the **Events** tab for the escrow's history, newest first.

![The Events tab with Time, Event, Owner, Token, Amount and Transaction columns](https://docs.settlemint.com/docs/screenshots/console-escrow-detail-events.light.en.webp)

[Screenshot] The Events tab shows a table of the escrow's events with "Time", "Event", "Owner", "Token", "Amount" and "Transaction" columns, where each event reads in plain words such as "Deposit", "Lock" or "Payment".

The "Event" column reads "Deposit", "Withdrawal", "Lock", "Unlock", "Relock", "Payment", "Booking", "Reclaim", "Surplus sweep", "Forced transfer" or "Recovery". A forced transfer and a recovery show the owner the units came from. A surplus sweep, which pays out tokens that reached the escrow without a deposit, shows no owner. A recovery moves a lost wallet's unlocked balance to its replacement wallet. The **Transaction** column links to the transaction that emitted the event. Sort by "Time" to reverse the order.

## Move units out with the forced-transfer API [#move-units-out-with-the-forced-transfer-api]

A forced transfer cannot be undone: once it settles, the escrow keeps no claim on the units.

The Console has no forced-transfer control for an escrow. A wallet that holds the token's custodian role sends `POST /api/v2/addons/escrows/{escrowAddress}/forced-transfers` through the Platform API with the token, the owner, the recipient, the amount and the locks to draw from. [Forced transfer](https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow#forced-transfer) gives the rules the escrow applies, and the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2) has the request and response. For a token that is not a DALP token, such as an outside quote currency, the escrow takes a forced transfer only from its controller, such as the venue or the rail wallet, and from no custodian.

The owner, token and lock identifiers are on the **Locks** tab. Only the organisation's Owner and Platform admin accounts see that tab, so a token custodian with neither role gets the identifiers from one of them. The escrow draws the owner's unlocked balance first, then the listed locks in the order you give them.

For a lock that backs a bank rail cash-out, the Platform API allows only the recipient that the cash-out's state permits. The escrow contract does not check the recipient, so a custodian who sends the forced transfer to the chain directly can choose any recipient. [Empty an escrow the old wallet controls](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#empty-an-escrow-the-old-wallet-controls) lists the recipient for each state.

## You should see [#you-should-see]

- The escrow you looked for is in the list.
- For each token its "Held" column lists, the amount matches the sum of "Total" for that token on the **Balances** tab.
- The "Open locks" figure in the header matches the count of locks on the "Locks" tab with the "Status" filter on "Open".
- After a forced transfer, the "Events" tab shows a "Forced transfer" row with a link to its transaction, the owner's "Total" for that token drops by the amount moved, and a lock it emptied shows "Forced".

## Troubleshooting [#troubleshooting]

**Escrows is missing from the sidebar**

The entry shows only to the organisation's Owner and to a Platform admin, and only once the system has an escrow
add-on deployed. A Venue manager who sees "Venues" does not see **Escrows** for that reason alone. Ask the
organisation's Owner or a Platform admin to open the page.

**An escrow I expect is not in the list**

The list shows the escrows that your system's escrow factory created. An escrow appears once the platform has indexed
the block that created it, so a venue or gateway created a moment ago can be missing for that time. An escrow whose
escrow factory has been archived is left out of the list. Opening an address that is not an escrow of your system
shows the Console's not-found page.

**A lock shows Reclaimable now but is still open**

Reaching the date does not move the units. A reclaim is a separate transaction that any wallet may send to the escrow,
and the Console does not send it. Until someone reclaims the lock or the controller moves it, the units stay in the
lock and the status stays **Open**.

**The forced transfer is refused**

A wallet without the custodian role on the token gets `403` with `DALP-9703`, and a refused transfer gets `409` with
`DALP-9702` and a `reason` in the response. Reasons include a lock that is not an open lock of that owner and token,
an amount larger than the owner's unlocked balance plus the listed locks, a lock that backs a bank rail cash-out the
bank may still pay, and a lock that backs an unpaid cash-out when no compromised rail wallet rotation is open. The
[error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) lists both codes.