# Wallet restriction API

Source: https://docs.settlemint.com/docs/console/participants/restricted-wallet-api
The Platform API and CLI calls that restrict a wallet across tokens, list and read restrictions, lift them, repeat a request safely, and the errors they return.

This reference covers the Platform API and CLI operations behind [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet): creating, listing, reading, retrying, and lifting wallet restrictions, updating the global address block list, and handling error codes.

## API routes [#api-routes]

The Platform API exposes five restriction operations: restrict, list, read, lift, and [request position release](https://docs.settlemint.com/docs/console/participants/held-positions#send-a-release-request). The CLI, SDK, and [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) cover the first four.

Authenticate with an [API key](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys), which acts with its creator's permissions, skips wallet verification, and returns `403` `DALP-17440` during security cooling-off. Console sessions send `walletVerification` in the request body instead. Pass `X-Chain-Id` to target a non-default network.

### Send a restrict request [#send-a-restrict-request]

Pass `walletAddress`, `scope` (`{"kind": "all"}` for every held token, or `{"kind": "tokens", "tokens": [...]}` for 1 to 50 specific token addresses), and `reason`:

```bash
curl -X POST "https://your-instance.example.com/api/v2/restrictions" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "scope": { "kind": "all" },
    "reason": { "code": "aml-review", "text": "Transaction monitoring alert, case 2026-0417" }
  }'
```

CLI equivalent:

```bash
dalp create restrictions --body '{
  "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "scope": { "kind": "all" },
  "reason": { "code": "aml-review", "text": "Transaction monitoring alert, case 2026-0417" }
}'
```

The endpoint returns `200` when all freezes and any module call settle, or `202` with a `Location` header if any token is `queued` or `chain.state` is `pending`. Owners, Platform administrators, and Compliance managers poll the `Location` URL to settle queued work, while other Custodian callers repeat the same `POST` request (polling `GET` returns `404` `DALP-17457` for them).

Partial outcomes are normal: inspect `data.summary` and each `data.tokens` entry. In the example below, the Owner holds Custodian on two of three tokens (one paused), lacks Custodian on the third (`DALP-0712`), and sees one held XvP position in `positions` ([Open positions and holds](https://docs.settlemint.com/docs/console/participants/held-positions#open-positions-and-holds), with unreachable sources listed in `positionsUnavailable`):

```json
{
  "data": {
    "id": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
    "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "participantId": "participant_3b1f",
    "scope": "all",
    "reason": {
      "code": "aml-review",
      "text": "Transaction monitoring alert, case 2026-0417"
    },
    "status": "active",
    "createdBy": "user_8f3a2c",
    "createdAt": "2026-10-25T12:00:00.000Z",
    "liftedBy": null,
    "liftedAt": null,
    "liftNote": null,
    "summary": {
      "total": 3,
      "frozen": 2,
      "queued": 0,
      "failed": 1,
      "alreadyFrozen": 0,
      "lifted": 0
    },
    "chain": {
      "state": "no-module",
      "action": null,
      "transactionHash": null,
      "failure": null,
      "updatedAt": null
    },
    "carriedFrom": null,
    "tokens": [
      {
        "token": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "tokenName": "Northwind Coffee Series A Bond",
        "tokenSymbol": "NWCAB",
        "status": "frozen",
        "paused": false,
        "transactionId": "0198f1a2-4a5b-7c6d-8e9f-0a1b2c3d4e5f",
        "transactionHash": "0x2a8f0d4c1b6e39a7c05d8f21b4e7a63c9d0f5b18e24a7c36d91b0f8e5a3c7d24",
        "failure": null,
        "updatedAt": "2026-10-25T12:00:07.000Z"
      },
      {
        "token": "0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9",
        "tokenName": "Northwind Real Estate Fund",
        "tokenSymbol": "NWREF",
        "status": "frozen",
        "paused": true,
        "transactionId": "0198f1a2-4a5c-7c6d-8e9f-0a1b2c3d4e60",
        "transactionHash": "0x5c1d9e7a3b0f2486d1c7e5a9b3f08d24c6e1a7b95d3f20c84e6a1b7d9c3f5e02",
        "failure": null,
        "updatedAt": "2026-10-25T12:00:07.000Z"
      },
      {
        "token": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
        "tokenName": "Northwind Treasury Note",
        "tokenSymbol": "NWTN",
        "status": "failed",
        "paused": false,
        "transactionId": null,
        "transactionHash": null,
        "failure": {
          "code": "DALP-0712",
          "message": "This operation is not available to the caller",
          "fix": "Ask an administrator to grant one of the listed roles on this token."
        },
        "updatedAt": "2026-10-25T12:00:07.000Z"
      }
    ],
    "positions": [
      {
        "id": "xvp:0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0:0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
        "kind": "xvp-delivery",
        "token": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "tokenName": "Northwind Coffee Series A Bond",
        "tokenSymbol": "NWCAB",
        "amount": "400",
        "counterparty": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
        "value": "40500",
        "baseCurrency": "EUR",
        "valuation": "priced",
        "held": true,
        "releases": []
      }
    ],
    "positionsUnavailable": [],
    "positionReleases": []
  },
  "links": {
    "self": "/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

`positionReleases` lists every release requested on the restriction, oldest first, with its `positionId`, `positionKind`, `token`, `state`, `reference`, requester, approver, and both timestamps. Releases stay there after their position settles or closes and leaves `positions`. If DALP cannot read release history, reading the restriction returns `503` so a report never shows an empty history by mistake. Restrict, lift, and release requests still return success with an empty `positionReleases` array because their write is already saved.

### List and read restrictions [#list-and-read-restrictions]

Filter restrictions (newest first) by `walletAddress`, `participantId`, `status` (`active` or `lifted`), `reasonCode`, or `createdAt` ([Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination)), then fetch one by ID to inspect its per-token records:

```bash
curl -g "https://your-instance.example.com/api/v2/restrictions?filter[walletAddress]=0x8ba1f109551bD432803012645Ac136ddd64DBA72&filter[status]=active" \
  -H "X-Api-Key: sm_dalp_..."

curl "https://your-instance.example.com/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b" \
  -H "X-Api-Key: sm_dalp_..."
```

CLI equivalents: `dalp get restrictions` (see `--help` for filter flags) and `dalp get restrictions <restrictionId>`.

### Send a lift request [#send-a-lift-request]

Send `status: "lifted"` with an optional `note` (up to 500 characters). Every lift call (including retries) requires Custodian on at least one listed token:

```bash
curl -X PATCH "https://your-instance.example.com/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "lifted", "note": "Cleared after review" }'
```

```bash
dalp patch restrictions 0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b \
  --body '{ "status": "lifted", "note": "Cleared after review" }'
```

Returns `200` once closed as `lifted`, or `202` with `Location` while any token is `lift-queued` or `chain.state` is `pending`. Repeating the lift retries only missing unfreezes and leaves an already-lifted restriction unchanged:

```json
{
  "data": {
    "id": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
    "walletAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "participantId": "participant_3b1f",
    "scope": "all",
    "reason": {
      "code": "aml-review",
      "text": "Transaction monitoring alert, case 2026-0417"
    },
    "status": "lifted",
    "createdBy": "user_8f3a2c",
    "createdAt": "2026-10-25T12:00:00.000Z",
    "liftedBy": "user_8f3a2c",
    "liftedAt": "2026-10-26T09:30:08.000Z",
    "liftNote": "Cleared after review",
    "summary": {
      "total": 3,
      "frozen": 0,
      "queued": 0,
      "failed": 1,
      "alreadyFrozen": 0,
      "lifted": 2
    },
    "chain": {
      "state": "no-module",
      "action": null,
      "transactionHash": null,
      "failure": null,
      "updatedAt": null
    },
    "carriedFrom": null,
    "tokens": [
      {
        "token": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "tokenName": "Northwind Coffee Series A Bond",
        "tokenSymbol": "NWCAB",
        "status": "lifted",
        "paused": false,
        "transactionId": "0198f6d3-6b7c-7d8e-9f0a-1b2c3d4e5f60",
        "transactionHash": "0x9b4e1f7c2a6d8035e1b9c4a7f2d60e3b8a5c1d9f4e7b2a60c3d8f5e1a9b7c402",
        "failure": null,
        "updatedAt": "2026-10-26T09:30:07.000Z"
      },
      {
        "token": "0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9",
        "tokenName": "Northwind Real Estate Fund",
        "tokenSymbol": "NWREF",
        "status": "lifted",
        "paused": true,
        "transactionId": "0198f6d3-6b7d-7d8e-9f0a-1b2c3d4e5f61",
        "transactionHash": "0x3d7a9c1e5b2f48067a1c9e3d5b7f2a4c6e8091b3d5f7a2c4e6a8b0d2f4c6e8a1",
        "failure": null,
        "updatedAt": "2026-10-26T09:30:08.000Z"
      },
      {
        "token": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
        "tokenName": "Northwind Treasury Note",
        "tokenSymbol": "NWTN",
        "status": "failed",
        "paused": false,
        "transactionId": null,
        "transactionHash": null,
        "failure": {
          "code": "DALP-0712",
          "message": "This operation is not available to the caller",
          "fix": "Ask an administrator to grant one of the listed roles on this token."
        },
        "updatedAt": "2026-10-25T12:00:07.000Z"
      }
    ],
    "positions": [
      {
        "id": "xvp:0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0:0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
        "kind": "xvp-delivery",
        "token": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "tokenName": "Northwind Coffee Series A Bond",
        "tokenSymbol": "NWCAB",
        "amount": "400",
        "counterparty": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
        "value": "40500",
        "baseCurrency": "EUR",
        "valuation": "priced",
        "held": false,
        "releases": []
      }
    ],
    "positionsUnavailable": [],
    "positionReleases": []
  },
  "links": {
    "self": "/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

### Repeat a request safely [#repeat-a-request-safely]

Repeating `POST /api/v2/restrictions` with the same reason code, note, and scope kind continues the active restriction rather than duplicating it:

- Freezes newly covered tokens.
- Retries failed tokens.
- Resumes accepted `queued` freezes without duplicating transactions.

Changing the reason, note, or scope kind returns `409` (`DALP-17458`). If the wallet no longer holds tokens, only Owners, Platform administrators, and Compliance managers can continue the restriction (others receive `422`). Callers without restriction-read access receive a redacted response showing only tokens where they hold Custodian, no free-text notes, and `positions` and `positionReleases` set to `null`. Both write endpoints also accept an optional `Idempotency-Key` header.

### Add a wallet to the address block list [#add-a-wallet-to-the-address-block-list]

To block both incoming and outgoing transfers on every bound token, update the global `address-block-list-v2` control ([Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls)) with a Compliance manager key. First read `/api/v2/system/compliance-modules` to find the binding's `moduleAddress` (`instanceAddress`) and existing `parameters.addresses`:

```bash
curl "https://your-instance.example.com/api/v2/system/compliance-modules" \
  -H "X-Api-Key: sm_dalp_..."
```

Because `configure` replaces the entire address list, include every existing address from `parameters.addresses` alongside the new wallet (omit `instanceAddress` only if `globalConfigs` is empty):

```bash
curl -X POST "https://your-instance.example.com/api/v2/system/compliance-modules/configure" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "instanceAddress": "0xa513E6E4b8f2a923D98304ec87F64353C4D5C853",
    "params": {
      "typeId": "address-block-list-v2",
      "module": "0x0165878A594ca255338adfa4d48449f69242Eb8F",
      "values": [
        "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
        "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
      ]
    }
  }'
```

Confirm by reading `/api/v2/system/compliance-modules/{moduleAddress}` after indexing.

### Errors [#errors]

| Status | Error | Cause | Resolution |
| --- | --- | --- | --- |
| `403` | [DALP-9485](https://docs.settlemint.com/docs/api-reference/errors) | Caller holds Custodian on none of the targeted tokens. | Grant Custodian on at least one token and retry. |
| `403` | [DALP-17440](https://docs.settlemint.com/docs/api-reference/errors) | API key owner is in a wallet security cooling-off period (`data.heldUntil`). | Retry after `data.heldUntil`. |
| `403` | [DALP-17461](https://docs.settlemint.com/docs/api-reference/errors) | System has the wallet restriction module and caller lacks Compliance manager on the system. | Grant Compliance manager on the system or delegate to a Compliance manager. |
| `404` | [DALP-17457](https://docs.settlemint.com/docs/api-reference/errors) | Restriction not found, or caller lacks read access and holds Custodian on none of its tokens. | Verify the restriction ID or ask an Owner or Compliance manager. |
| `409` | [DALP-17458](https://docs.settlemint.com/docs/api-reference/errors) | Active restriction exists with a different reason, note, or scope kind. | Repeat with the active restriction's exact reason, note, and scope, or lift it first. |
| `409` | [DALP-17460](https://docs.settlemint.com/docs/api-reference/errors) | A freeze is still settling on a token where you hold Custodian, so no unfreeze was sent. | Wait for settlement and retry the lift. |
| `422` | [DALP-17459](https://docs.settlemint.com/docs/api-reference/errors) | Wallet holds no tokens in this organisation, or none of the listed tokens exists in the active system. | Supply valid system tokens or use the global address block list. |
| `422` | [DALP-12119](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199) | Target address (`data.escrowAddress`) is a DALP escrow contract. | Restrict the owner's wallet instead ([Units in a DALP escrow](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet#units-in-a-dalp-escrow)). |