# Custody gateway API

Source: https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api
Walk a deposit and a withdrawal through the custody gateway routes, bind a client wallet and reinstate a suspended payout address.

The custody gateway routes live under `/api/v2/addons/custody-gateways`. They form the `custodyOps` operation group of the Platform API, and the generated API reference lists every route and schema. This page walks the routes in the order a deposit and a withdrawal use them. [Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages) lists what each stage means and who moves it. [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) explains the model.

## Before you call [#before-you-call]

- The "Self-custody" module must be on. With it off, every route answers `DALP-20531` (`platform.module.DISABLED`).
- Paths below are relative to `/api/v2/addons/custody-gateways`. `{gatewayAddress}` is the client's gateway address.
- Each write carries a `walletVerification` object that proves the acting wallet. A write answers `200` when it is final and `202` when it waits for a second approver. A write honours an `Idempotency-Key` header, so a retry with the same key does not repeat it. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) says how.
- Gateway manager actions need the gateway manager role on the acting wallet, and the screener actions need the screener role. A client acts with the wallet bound to its gateway.

## Bind the client wallet [#bind-the-client-wallet]

A gateway has no client wallet when it is created. Bind one before the client's own routes work:

```bash
curl -X PATCH "https://your-instance.example.com/api/v2/addons/custody-gateways/gateways/$GATEWAY/client-wallet" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"clientWallet": "0x...", "walletVerification": {...}}'
```

The wallet must belong to the gateway's client identity. The result is `{ "clientWallet": "0x..." }`. `GET /gateways/mine` then returns the gateway to the client, with the address the client deposits into.

## Walk a deposit [#walk-a-deposit]

1. The client reads the gateway with `GET /gateways/mine` and sends coins to its address, or records a deposit from a wallet with `POST /gateways/{gatewayAddress}/deposits`. The body is `{ "token", "amount", "walletVerification" }`.
2. List the gateway's deposits with `GET /gateways/{gatewayAddress}/deposits` and read one with `GET /gateways/{gatewayAddress}/deposits/{depositId}`. A new deposit rests at `Quarantined`.
3. The screener moves it with `POST /gateways/{gatewayAddress}/deposits/{depositId}/transitions`:

```bash
curl -X POST ".../gateways/$GATEWAY/deposits/$DEPOSIT/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "clear", "walletVerification": {...}}'
```

4. The operator transitions are `confirm-sender`, `clear`, `refuse`, `flag`, `unfreeze`, `renew-freeze`, `report`, `return`, `retry`, `custody-returned` and `recover`. The client transitions are `pull-back` and `exit`. `recover` also takes `"to"`, the wallet that receives the coins.
5. Read `GET .../deposits/{depositId}/screening` for the screening result and `POST .../deposits/{depositId}/notes` to add an operator note.

## Walk a withdrawal [#walk-a-withdrawal]

1. The client asks for the fee with `GET .../withdrawal-fee-quotes`, then creates the request with `POST /gateways/{gatewayAddress}/withdrawals`. The body is `{ "receiptToken", "shares", "payout", "walletVerification" }`. The payout address must be on the gateway's approved payout list.
2. List and read requests with `GET .../withdrawals` and `GET .../withdrawals/{requestId}`. Read `GET .../withdrawals/{requestId}/screening` for the screening result.
3. Move a request with `POST .../withdrawals/{requestId}/transitions`. The operator transitions are `clear`, `approve`, `reject`, `flag`, `unfreeze`, `renew-freeze`, `report`, `return` and `unfulfil`. The client transitions are `cancel`, `collect`, `exit` and `set-payout`, and `set-payout` also takes `"payout"`.
4. The client sets how it is paid with `PATCH .../auto-claim` (`{ "enabled", "walletVerification" }`) and `PATCH .../default-payout` (`{ "payout", "walletVerification" }`).

```bash
curl -X POST ".../gateways/$GATEWAY/withdrawals/$REQUEST/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "collect", "walletVerification": {...}}'
```

## Reinstate a payout address [#reinstate-a-payout-address]

A client flag suspends the gateway's payout addresses. Clearing the flag does not reinstate them. After review, a gateway manager reinstates one with the address's transitions route:

```bash
curl -X POST ".../gateways/$GATEWAY/approved-payouts/$ADDRESS/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "reinstate", "walletVerification": {...}}'
```

The other transitions on that route are `remove` and `suspend`. `GET .../approved-payouts` lists the addresses and their state, and `POST .../approved-payouts` adds one.

## Other routes [#other-routes]

| Route | Use |
| --- | --- |
| `GET .../client-flag`, `POST .../client-flag/transitions` | Read a client's flag and clear it. |
| `GET .../unsupported`, `POST .../unsupported/{recordId}/transitions` | Coins the gateway does not accept. Transitions are `confirm-sender`, `ignore`, `return`, `enable` and `recover`. |
| `POST .../transitions` | Pause, unpause or close a gateway with `pause`, `unpause` or `close`. |
| `GET /gateways`, `GET /gateways/{gatewayAddress}`, `PATCH .../settings` | List gateways, read one and change its settings. |
| `GET /profiles`, `GET /signers`, `GET /role-members`, `GET /tokens` | Read the add-on's profiles, keeper and screener wallets, role holders and enabled coins. |

## Related pages [#related-pages]

- [Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages)
- [Review deposits and withdrawals in the Console](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review)
- [Calling routes with the SDK](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes)