# Custody gateway stages

Source: https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages
Every stage a custody gateway deposit or withdrawal can be in, what the client and the operator see, who moves it and which time limit applies.

A gateway deposit and a gateway withdrawal each move through a fixed set of stages. The gateway emits `DepositStageChanged` and `WithdrawalStageChanged` on every move. The names below are the names those events carry. The [concept page](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) explains the model, and the [how-to](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api) walks the routes that move a record.

The "Client sees" column is the wording in the Investor portal and "Operator sees" is the wording in the Console. A stage that rests waits for a person or a time limit. A stage that ends never moves again.

## Deposit stages [#deposit-stages]

| Stage | Client sees | Operator sees | Rests or ends | Moved by, with the call and event | Time limit |
| --- | --- | --- | --- | --- | --- |
| `None` | Nothing | Nothing | Not a stage. No deposit has this id. | The keeper records a deposit and the gateway emits `DepositRecorded` with its first stage. | None |
| `Quarantined` | "In review" | "Quarantined, awaiting screener" | Rests | Entered when the keeper records the transfer. The screener leaves it with `clear` or `refuse`. The client leaves it with `pull-back` or `exit`. Gateway managers leave it with `return`. | `pull-back-after` opens the client's `pull-back`. `paused-exit-after` opens `exit` while the gateway is paused. |
| `Frozen` | "On hold" | "Frozen" | Rests | The screener or a gateway manager moves a `Quarantined` or `AwaitingCustody` deposit here with `flag`. Gateway managers end it with `unfreeze`, keep it with `renew-freeze` or lock it with `report`. | `freeze-expiry` ends a freeze that is neither renewed nor reported. |
| `MintRefused` | "Not credited" | "Mint refused" | Rests | `clear` enters it when the gateway cannot mint the receipts. The keeper leaves it with `retry`. Gateway managers can `return` or `recover` it. | None |
| `AwaitingCustody` | "Waiting for custody" | "Awaiting custody" | Rests | `clear` enters it for a coin set to wait for custody. The keeper leaves it when the custodian accepts, which settles it, or reports the custodian's return, after which gateway managers use `custody-returned` or `recover`. | `custody-answer-time` is the time the custodian has to accept the forward. |
| `Settled` | "Completed" | "Settled" | Ends | `clear` or `retry` mints the receipts. The custodian's acceptance settles an `AwaitingCustody` deposit. The gateway emits `DepositSettled`. | None |
| `Returned` | "Returned" | "Returned" | Ends | `refuse`, `pull-back`, `exit`, `return` or `custody-returned` pay the coins to the confirmed sender. `returnedBy` says who. | None |
| `Recovered` | "Recovered" | "Recovered" | Ends | Gateway managers move the coins to a destination they name with `recover`. | None |

## Withdrawal stages [#withdrawal-stages]

| Stage | Client sees | Operator sees | Rests or ends | Moved by, with the call and event | Time limit |
| --- | --- | --- | --- | --- | --- |
| `None` | Nothing | Nothing | Not a stage. No request has this id. | The client creates a request, which enters `Requested`. | None |
| `Requested` | "Requested" | "Requested" | Passes at once | Entered when the client requests or names a payout address. The gateway checks the payout address, the minimum and the daily maximum, then routes the request. A failed check returns the receipts with the reason `Refused`. | None |
| `AwaitingPayout` | "Waiting for payout address" | "Awaiting payout address" | Rests | Entered when receipts arrive by transfer with no payout address. The client leaves it with `set-payout` or `cancel`. Screeners and gateway managers can `reject` it. | `payout-address-time` expires the request and returns the receipts with the reason `TimeLimit`. |
| `InReview` | "In review" | "In review" | Rests | The screener `clear`s screening and the gateway managers `approve` it. When nothing is left to clear, the request moves to `AwaitingFunds`. Screeners and gateway managers can `reject` it. The client can `cancel` it. | None |
| `AwaitingFunds` | "Waiting for funds" | "Awaiting funds" | Rests | The keeper's `fulfil` reserves the coins and moves the request to `Claimable`. | `cancel-after` opens the client's `cancel`. Unset or 0 means never. |
| `Claimable` | "Ready to collect" | "Claimable" | Rests | The client `collect`s, or the keeper collects when `auto-claim` is on. Gateway managers can `unfulfil` it back to `AwaitingFunds`. | None |
| `Settled` | "Completed" | "Settled" | Ends | The claim pays the payout address. The gateway emits `WithdrawalStageChanged` and `Withdraw`. | None |
| `ReturnPending` | "Returning receipts" | "Return pending" | Rests | A return could not pay the receipts out, because the receiving wallet is frozen or unknown. `completeReturn` finishes it once the wallet can receive. | None |
| `ReceiptReturned` | "Receipts returned" | "Receipts returned" | Ends | `reject`, `cancel`, `exit`, a refusal, the payout address time limit or a return of a frozen request pays the receipts back. `returnReason` says why. | None |

## Notes [#notes]

### Frozen is not a stored stage [#frozen-is-not-a-stored-stage]

A freeze is a flag on a record, not a stage. A frozen deposit keeps the stage it was frozen from, and a read reports it with `isFrozen` set. `DepositStageChanged` still carries `Frozen` when a freeze starts or renews, and the Console's "Stage" column shows "Frozen" while the freeze is live. A frozen withdrawal keeps its stage in the same way, and the Portal shows "On hold". Unfreezing restores the stage the record had.

### The reported mark [#the-reported-mark]

`report` marks a frozen record as reported. A reported record never expires its freeze and nobody can unfreeze it. When a client's flag clears, reported records stay frozen.

### `returnedBy` and `returnReason` [#returnedby-and-returnreason]

A deposit that ends as `Returned` carries `returnedBy`: `None`, `Client`, `Screener` or `Managers`. A withdrawal that ends as `ReceiptReturned` or waits in `ReturnPending` carries `returnReason`: `None`, `Refused`, `Rejected`, `Cancelled`, `TimeLimit`, `FrozenReturn` or `PausedExit`.

### Time limits [#time-limits]

Each limit is a setting that resolves from the gateway, then its profile, then the add-on default. The terms in force when a record was created are the terms it keeps. `freeze-expiry` and `paused-exit-after` are required on every enabled coin.